cozyclay 3.1.0 → 3.1.2

package/src/sculpt-recipe-read.js

@@ -0,0 +1,65 @@
+/**
+ * Readers shared by the sculpt recipe modules (sculpt-recipe.js, sculpt-shapes.js,
+ * sculpt-part-fields.js). Each one refuses a bad value with the field's path
+ * instead of clamping it. Pure: no three.js.
+ */
+
+export const tidy = (value) => {
+	const rounded = Math.round(value * 1e4) / 1e4;
+	return rounded === 0 ? 0 : rounded;
+};
+export const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+
+export class RecipeError extends Error {
+	constructor(path, message) {
+		super(`${path}: ${message}`);
+		this.path = path;
+	}
+}
+
+export function readVector(value, path, fallback, check) {
+	if (value === undefined && fallback) return [...fallback];
+	if (!Array.isArray(value) || value.length !== 3 || !value.every(isFiniteNumber)) {
+		throw new RecipeError(path, `must be three numbers [x, y, z], got ${JSON.stringify(value)}`);
+	}
+	value.forEach((component, axis) => check(component, `${path}[${axis}]`));
+	return value.map(tidy);
+}
+
+export function readUnit(value, path, fallback, min, max) {
+	if (value === undefined) return fallback;
+	if (!isFiniteNumber(value) || value < min || value > max) {
+		throw new RecipeError(path, `must be a number from ${min} to ${max}, got ${JSON.stringify(value)}`);
+	}
+	return tidy(value);
+}
+
+export function readInteger(value, path, fallback, min, max) {
+	if (value === undefined && fallback !== undefined) return fallback;
+	if (!Number.isInteger(value) || value < min || value > max) {
+		throw new RecipeError(path, `must be a whole number from ${min} to ${max}, got ${JSON.stringify(value)}`);
+	}
+	return value;
+}
+
+/** A pattern seed (detail bumps, scatter layout): 0 unless the recipe picks another. */
+export const readSeed = (value, path) => readInteger(value, path, 0, 0, 999999);
+
+export function readChoice(value, path, fallback, choices) {
+	if (value === undefined && fallback !== undefined) return fallback;
+	if (!choices.includes(value)) throw new RecipeError(path, `must be one of ${choices.join(", ")}; got ${JSON.stringify(value)}`);
+	return value;
+}
+
+const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
+const HEX_LONG = /^#?([0-9a-f]{6})$/i;
+
+/** `#rgb` or `#rrggbb` (the `#` optional), as lower-case `#rrggbb`. */
+export function readHexColor(value, path) {
+	const text = typeof value === "string" ? value.trim() : "";
+	const short = HEX_SHORT.exec(text);
+	if (short) return `#${short[1].toLowerCase().replace(/./g, (digit) => digit + digit)}`;
+	const long = HEX_LONG.exec(text);
+	if (long) return `#${long[1].toLowerCase()}`;
+	throw new RecipeError(path, `colour must be #rgb or #rrggbb, got ${JSON.stringify(value)}`);
+}

package/src/sculpt-recipe.js

@@ -15,8 +15,12 @@
  * Contract: docs/sculpt-from-image.md.
  */
 
+import { RecipeError, readHexColor, readVector, tidy } from "./sculpt-recipe-read.js";
+import { SCULPT_SHAPES, SCULPT_SHAPE_KEYS, SCULPT_SHAPE_SPECS } from "./sculpt-shapes.js";
+import { SCULPT_PART_FIELDS } from "./sculpt-part-fields.js";
+import { checkSculptCutters } from "./sculpt-cutters.js";
+
 const SCULPT_RECIPE_VERSION = 1;
-const SCULPT_SHAPES = Object.freeze(["blob", "box", "cylinder", "torus", "frame"]);
 export const SCULPT_LIMITS = Object.freeze({
 	/** after mirrors are expanded */
 	maxParts: 48,
@@ -24,6 +28,8 @@ export const SCULPT_LIMITS = Object.freeze({
 	maxExtent: 20,
 	maxOffset: 20,
 	maxDepth: 8,
+	/** scatter items across the whole recipe, after mirrors */
+	maxScatterItems: 12000,
 });
 const SCULPT_DEFAULT_COLOR = "#c2c6c8";
 /** The suffix a mirrored copy's id gets. `.` is outside the id alphabet, so a
@@ -32,61 +38,13 @@ export const SCULPT_MIRROR_SUFFIX = ".mirror";
 const MIN_HEIGHT = 0.05;
 
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
-const HEX_LONG = /^#?([0-9a-f]{6})$/i;
-const PART_KEYS = new Set(["id", "shape", "size", "position", "rotation", "color", "parent", "mirror", "roundness", "taper", "border"]);
-const SHAPE_KEYS = {
-	blob: new Set(["roundness", "taper"]),
-	box: new Set(["roundness"]),
-	cylinder: new Set(["taper"]),
-	torus: new Set(),
-	frame: new Set(["border"]),
-};
-const DEFAULT_ROUNDNESS = { blob: 0.5, box: 0.1 };
-
-const tidy = (value) => {
-	const rounded = Math.round(value * 1e4) / 1e4;
-	return rounded === 0 ? 0 : rounded;
-};
-const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const PART_KEYS = new Set(["id", "shape", "size", "position", "rotation", "color", "parent", "mirror", ...SCULPT_SHAPE_KEYS, ...SCULPT_PART_FIELDS.map((field) => field.key)]);
 const wrapDegrees = (deg) => {
 	const wrapped = ((((deg + 180) % 360) + 360) % 360) - 180;
 	return wrapped === -180 ? 180 : wrapped;
 };
 
-class RecipeError extends Error {
-	constructor(path, message) {
-		super(`${path}: ${message}`);
-		this.path = path;
-	}
-}
-
-function readColor(value, path) {
-	if (value === undefined) return SCULPT_DEFAULT_COLOR;
-	const text = typeof value === "string" ? value.trim() : "";
-	const short = HEX_SHORT.exec(text);
-	if (short) return `#${short[1].toLowerCase().replace(/./g, (digit) => digit + digit)}`;
-	const long = HEX_LONG.exec(text);
-	if (long) return `#${long[1].toLowerCase()}`;
-	throw new RecipeError(path, `colour must be #rgb or #rrggbb, got ${JSON.stringify(value)}`);
-}
-
-function readVector(value, path, fallback, check) {
-	if (value === undefined && fallback) return [...fallback];
-	if (!Array.isArray(value) || value.length !== 3 || !value.every(isFiniteNumber)) {
-		throw new RecipeError(path, `must be three numbers [x, y, z], got ${JSON.stringify(value)}`);
-	}
-	value.forEach((component, axis) => check(component, `${path}[${axis}]`));
-	return value.map(tidy);
-}
-
-function readUnit(value, path, fallback, min, max) {
-	if (value === undefined) return fallback;
-	if (!isFiniteNumber(value) || value < min || value > max) {
-		throw new RecipeError(path, `must be a number from ${min} to ${max}, got ${JSON.stringify(value)}`);
-	}
-	return tidy(value);
-}
+const readColor = (value, path) => (value === undefined ? SCULPT_DEFAULT_COLOR : readHexColor(value, path));
 
 function normalizePart(raw, index) {
 	const at = `parts[${index}]`;
@@ -101,8 +59,9 @@ function normalizePart(raw, index) {
 	if (!SCULPT_SHAPES.includes(raw.shape)) {
 		throw new RecipeError(`${where}.shape`, `must be one of ${SCULPT_SHAPES.join(", ")}; got ${JSON.stringify(raw.shape)}`);
 	}
-	for (const key of ["roundness", "taper", "border"]) {
-		if (raw[key] !== undefined && !SHAPE_KEYS[raw.shape].has(key)) {
+	const spec = SCULPT_SHAPE_SPECS[raw.shape];
+	for (const key of SCULPT_SHAPE_KEYS) {
+		if (raw[key] !== undefined && !spec.keys.includes(key)) {
 			throw new RecipeError(`${where}.${key}`, `does not apply to a ${raw.shape}`);
 		}
 	}
@@ -129,20 +88,8 @@ function normalizePart(raw, index) {
 	};
 	if (raw.parent !== undefined) part.parent = raw.parent;
 	if (raw.mirror === true) part.mirror = true;
-	if (SHAPE_KEYS[raw.shape].has("roundness")) part.roundness = readUnit(raw.roundness, `${where}.roundness`, DEFAULT_ROUNDNESS[raw.shape], 0, 1);
-	if (SHAPE_KEYS[raw.shape].has("taper")) part.taper = readUnit(raw.taper, `${where}.taper`, 0, -1, 1);
-	if (raw.shape === "frame") {
-		const limit = Math.min(size[0], size[1]) / 2;
-		const fallback = tidy(Math.min(size[0], size[1]) * 0.15);
-		const border = raw.border === undefined ? fallback : raw.border;
-		if (!isFiniteNumber(border) || border <= 0 || border >= limit) {
-			throw new RecipeError(`${where}.border`, `must be above 0 and below half the frame's smaller side (${tidy(limit)} m), got ${JSON.stringify(raw.border)}`);
-		}
-		part.border = tidy(border);
-	}
-	if (raw.shape === "torus" && size[2] >= Math.min(size[0], size[1])) {
-		throw new RecipeError(`${where}.size`, "a torus's tube (size[2]) must be thinner than its outer diameter");
-	}
+	spec.read(raw, part, where);
+	for (const field of SCULPT_PART_FIELDS) if (raw[field.key] !== undefined) field.read(raw, part, where);
 	return part;
 }
 
@@ -196,10 +143,16 @@ export function normalizeSculptRecipe(input) {
 			seen.add(part.id);
 		}
 		partDepths(parts);
+		checkSculptCutters(parts);
 		const recipe = { version: SCULPT_RECIPE_VERSION, parts };
-		const count = expandSculptParts(recipe).length;
-		if (count > SCULPT_LIMITS.maxParts) {
-			throw new RecipeError("recipe.parts", `expands to ${count} parts with mirrors; the limit is ${SCULPT_LIMITS.maxParts}`);
+		const drawn = expandSculptParts(recipe);
+		if (drawn.length > SCULPT_LIMITS.maxParts) {
+			throw new RecipeError("recipe.parts", `expands to ${drawn.length} parts with mirrors; the limit is ${SCULPT_LIMITS.maxParts}`);
+		}
+		// A scatter is one part but many drawn items; the frame rate pays per item.
+		const items = drawn.reduce((sum, part) => sum + (part.shape === "scatter" ? part.count : 0), 0);
+		if (items > SCULPT_LIMITS.maxScatterItems) {
+			throw new RecipeError("recipe.parts", `scatter parts draw ${items} items with mirrors; the limit is ${SCULPT_LIMITS.maxScatterItems}`);
 		}
 		return { ok: true, recipe };
 	} catch (error) {
@@ -210,8 +163,9 @@ export function normalizeSculptRecipe(input) {
 
 /**
  * A recipe edited part by part instead of rewritten. `edits` are applied in
- * order: `{ set: id, ...fields }` merges fields into one part (`parent: null`
- * and `mirror: false` clear), `{ add: part }` appends, `{ remove: id }` drops a
+ * order: `{ set: id, ...fields }` merges fields into one part (`parent: null`,
+ * `mirror: false` and null for an optional field such as `detail` clear),
+ * `{ add: part }` appends, `{ remove: id }` drops a
  * part and every part below it. The result is normalized as a whole, so an edit
  * that leaves the recipe undrawable is refused with the usual path.
  * Returns `{ ok: true, recipe, changed: [ids] }` or `{ ok: false, error, path }`.
@@ -249,8 +203,9 @@ export function patchSculptRecipe(recipe, edits) {
 		const next = { ...parts[found], ...fields };
 		if (fields.parent === null) delete next.parent;
 		if (fields.mirror === false) delete next.mirror;
+		for (const field of SCULPT_PART_FIELDS) if (fields[field.key] === null) delete next[field.key];
 		// Shape-specific defaults belong to the old shape, not the new one.
-		if ("shape" in fields) for (const key of ["roundness", "taper", "border"]) if (!(key in fields)) delete next[key];
+		if ("shape" in fields) for (const key of SCULPT_SHAPE_KEYS) if (!(key in fields)) delete next[key];
 		parts[found] = next;
 		changed.add(id);
 	}
@@ -298,7 +253,8 @@ function applyMatrix(m, [x, y, z]) {
 
 /** A reflection across x = 0 of the parent frame keeps the part's shape and
  * negates the lateral axis only: position.x flips, and the yaw and roll turn
- * the other way. All five shapes are symmetric about their own x, so no
+ * the other way. Shapes symmetric about their own x need nothing more; the
+ * others reflect their own data (SCULPT_SHAPE_SPECS[shape].mirror), so no
  * negative scale (and no winding flip) is needed. */
 function mirroredPart(part, parentId) {
 	const copy = {
@@ -308,6 +264,7 @@ function mirroredPart(part, parentId) {
 		rotation: [part.rotation[0], tidy(-part.rotation[1]), tidy(-part.rotation[2])],
 	};
 	delete copy.mirror;
+	SCULPT_SHAPE_SPECS[copy.shape].mirror?.(copy);
 	if (parentId !== undefined) copy.parent = parentId;
 	return copy;
 }
@@ -352,10 +309,11 @@ function localCorners(part) {
 	return corners;
 }
 
+/** A cutter (op) is not drawn and only takes from its parent, so it never widens the box. */
 export function sculptBounds(recipe) {
 	const min = [Infinity, Infinity, Infinity];
 	const max = [-Infinity, -Infinity, -Infinity];
-	for (const part of expandSculptParts(recipe)) {
+	for (const part of expandSculptParts(recipe).filter((drawn) => !drawn.op)) {
 		for (const corner of localCorners(part)) {
 			const point = applyMatrix(part.matrix, corner);
 			for (let axis = 0; axis < 3; axis += 1) {

package/src/sculpt-run.js

@@ -49,7 +49,7 @@ function dataUrlFromSheet(sheet) {
 const referenceArg = reference => (reference?.assetId ? { assetId: reference.assetId } : { dataUrl: reference?.dataUrl });
 
 // The recipe rules the agent needs to get object.sculpt right the first time (sculpt-recipe.js).
-const RECIPE_RULES = "Recipe: { \"version\": 1, \"parts\": [{ \"id\", \"shape\", \"size\": [x,y,z] metres, \"position\": [x,y,z] centre, \"rotation\": [x,y,z] degrees, \"color\": \"#rrggbb\", \"parent\"?, \"mirror\"?, \"roundness\"? 0-1, \"taper\"? }] }. id: lowercase a-z, 0-9 and -, starting with a letter or digit, at most 40 characters. shape is exactly one of blob, box, cylinder, torus, frame (no cone, sphere or other names). Up to 48 parts after mirrors. Floor is y=0 (feet touch it), front is +z, the subject's left is +x, mirror: true adds the reflection across x=0. roundness works backwards from its name: 0 is a smooth ellipsoid and 1 is a rounded box. roundness belongs only on blob and box, taper only on blob: leave both off cylinder, torus and frame. Keep roundness at 0.2 or below on every organic part (body, belly, head, face, limbs); go above 0.3 only for hard-edged objects. Use box only for hard-edged things.";
+const RECIPE_RULES = "Recipe: { \"version\": 1, \"parts\": [{ \"id\", \"shape\", \"size\": [x,y,z] metres, \"position\": [x,y,z] centre, \"rotation\": [x,y,z] degrees, \"color\": \"#rrggbb\", \"parent\"?, \"mirror\"?, \"roundness\"? 0-1, \"taper\"? }] }. id: lowercase a-z, 0-9 and -, starting with a letter or digit, at most 40 characters. shape is exactly one of blob, box, cylinder, torus, frame, lathe, tube, extrude, loft, convex, scatter (no cone, sphere or other names): lathe { \"profile\": [[r 0-1, y 0-1], ...] } for turned forms (pot, bottle, bowl), tube { \"path\": [[x,y,z] each -0.5..0.5 of size], \"thickness\" m } for ropes, tails, handles and limbs that bend, extrude { \"outline\": [[x,y] -0.5..0.5] } for flat cut shapes (ears, fins, leaves, signs), loft { \"sections\": [{ \"y\", \"w\", \"d\" }, ...] } for bodies whose cross-section changes, convex { \"seed\" } for rocks. Any part may add \"detail\": { \"amount\": 0-1 } for a lumpy surface, \"gradient\": { \"color\" } for a two-tone blend, or \"op\": \"subtract\" to cut its parent (a mouth, a hollow). Up to 48 parts after mirrors. Floor is y=0 (feet touch it), front is +z, the subject's left is +x, mirror: true adds the reflection across x=0. roundness works backwards from its name: 0 is a smooth ellipsoid and 1 is a rounded box. roundness belongs only on blob, box and extrude, taper only on blob, cylinder and tube: leave both off the other shapes. Keep roundness at 0.2 or below on every organic part (body, belly, head, face, limbs); go above 0.3 only for hard-edged objects. Use box only for hard-edged things.";
 
 // A compact score for the next turn: what is missing where, and which parts stick out.
 function reportText(report) {

package/src/sculpt-scatter-items.js

@@ -0,0 +1,183 @@
+/**
+ * The scatter items (sculpt-scatter-shape.js names them): small closed clay
+ * shapes, each built once and cached; a scatter part draws a clone of one as
+ * an InstancedMesh. Standing items (blade, tuft, flower) are about one unit
+ * tall from y = 0; lying items (leaf, pebble, twig) are about one unit long
+ * and lie on y = 0. All are centred on x = 0, so a reflected copy fits the
+ * same box. Each carries a grey `color` ramp that darkens its foot, so a
+ * field reads with depth (it multiplies the per-item colour in the shaded
+ * look; flat display modes ignore it).
+ *
+ *   stand   true: sized by the part's height on the ground
+ *   tilt    the most an item leans from its surface's normal, in degrees
+ *   cover   size against the spacing `count` leaves (lying items, shells)
+ */
+
+import * as THREE from "three";
+import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
+import { fbm3, seededRandom } from "./sculpt-noise.js";
+
+/** `sides` points around (cx, y, cz), ordered so a loft's faces point outward. */
+function ring(sides, rx, rz, y, cx = 0, cz = 0, twist = 0) {
+	const points = [];
+	for (let i = 0; i < sides; i += 1) {
+		const angle = twist + (i / sides) * 2 * Math.PI;
+		points.push([cx + rx * Math.cos(angle), y, cz - rz * Math.sin(angle)]);
+	}
+	return points;
+}
+
+/** A closed tube up through `rings` (bottom capped; a one-point last ring is
+ * a tip), shaded grey by `shade(0 bottom .. 1 top)`. */
+function loft(rings, shade) {
+	const positions = [], colours = [], index = [], starts = [];
+	rings.forEach((points, k) => {
+		starts.push(positions.length / 3);
+		const grey = shade(k / (rings.length - 1));
+		for (const point of points) {
+			positions.push(...point);
+			colours.push(grey, grey, grey);
+		}
+	});
+	for (let k = 0; k + 1 < rings.length; k += 1) {
+		const a = starts[k], b = starts[k + 1], n = rings[k].length;
+		for (let i = 0; i < n; i += 1) {
+			const j = (i + 1) % n;
+			if (rings[k + 1].length === 1) index.push(a + i, a + j, b);
+			else index.push(a + i, a + j, b + j, a + i, b + j, b + i);
+		}
+	}
+	for (let i = 1; i + 1 < rings[0].length; i += 1) index.push(starts[0], starts[0] + i + 1, starts[0] + i);
+	const geometry = new THREE.BufferGeometry();
+	geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+	geometry.setAttribute("color", new THREE.Float32BufferAttribute(colours, 3));
+	geometry.setIndex(index);
+	return geometry;
+}
+
+const footShade = (t) => 0.5 + 0.5 * Math.min(1, t * 1.4);
+
+/** A blade of grass: a flat three-sided spike curving toward +z. */
+function blade() {
+	const rings = [];
+	for (let k = 0; k < 4; k += 1) {
+		const t = k / 4, width = 0.04 * (1 - t) ** 0.7;
+		rings.push(ring(3, width, width * 0.4, t, 0, 0.18 * t * t, Math.PI / 2));
+	}
+	rings.push([[0, 1, 0.18]]);
+	return loft(rings, footShade);
+}
+
+/** Six blades fanned out from one root. */
+function tuft() {
+	const random = seededRandom(0x7a1f);
+	const blades = [];
+	for (let i = 0; i < 6; i += 1) {
+		const one = blade();
+		one.scale(1.3, 0.7 + 0.3 * random(), 1.3);
+		one.rotateX(0.2 + 0.35 * random());
+		one.rotateY((i / 6) * 2 * Math.PI + random() * 0.6);
+		blades.push(one);
+	}
+	return mergeGeometries(blades);
+}
+
+/** A stem with a five-petal head facing +y. */
+function flower() {
+	const stem = loft([ring(4, 0.02, 0.02, 0), ring(4, 0.018, 0.018, 0.45, 0.01, 0.02), ring(4, 0.016, 0.016, 0.8, 0, 0.03)], () => 0.55);
+	const petals = [];
+	for (let i = 0; i < 15; i += 1) {
+		const angle = (i / 15) * 2 * Math.PI, r = 0.24 * (0.7 + 0.3 * Math.cos(5 * angle));
+		petals.push([r * Math.cos(angle), 0.86, 0.03 - r * Math.sin(angle)]);
+	}
+	const head = loft([ring(15, 0.05, 0.05, 0.78, 0, 0.03), petals, ring(15, 0.09, 0.09, 0.93, 0, 0.03), [[0, 0.97, 0.03]]], () => 1);
+	return mergeGeometries([stem, head]);
+}
+
+/** A leaf lying on y = 0: a thin arched lens one unit long along z. */
+function leaf() {
+	const rings = [];
+	for (let k = 0; k < 6; k += 1) {
+		const t = k / 6, half = Math.max(0.015, 0.21 * Math.sin(Math.PI * Math.min(1, 0.15 + t)) ** 0.8);
+		rings.push(ring(6, half, 0.02, t, 0, -0.07 * Math.sin(Math.PI * t)));
+	}
+	rings.push([[0, 1, 0]]);
+	const geometry = loft(rings, (t) => 0.8 + 0.2 * t);
+	geometry.rotateX(Math.PI / 2);
+	return geometry;
+}
+
+/** A flattened, faceted stone; the facets read as gravel. */
+function pebble() {
+	const geometry = new THREE.IcosahedronGeometry(0.5, 1);
+	const position = geometry.getAttribute("position");
+	for (let i = 0; i < position.count; i += 1) {
+		const x = position.getX(i), y = position.getY(i), z = position.getZ(i);
+		const k = 1 + 0.2 * fbm3(x * 2.4 + 3.1, y * 2.4 + 1.7, z * 2.4 + 5.3, 11);
+		position.setXYZ(i, x * k, y * k * 0.5, z * k * 0.8);
+	}
+	geometry.deleteAttribute("uv");
+	geometry.setAttribute("color", new THREE.Float32BufferAttribute(new Array(position.count * 3).fill(1), 3));
+	return geometry;
+}
+
+/** A crooked stick with one side branch, lying along x. */
+function twig() {
+	const stick = (length, radius) => loft(Array.from({ length: 6 }, (_, k) => {
+		const t = k / 5;
+		return ring(5, radius * (1 - 0.5 * t), radius * (1 - 0.5 * t), t * length, 0.04 * Math.sin(t * 7.3), 0.03 * Math.sin(t * 4.1 + 1));
+	}), () => 0.85);
+	const branch = stick(0.35, 0.018);
+	branch.rotateX(-0.7);
+	branch.translate(0, 0.45, 0);
+	const geometry = mergeGeometries([stick(1, 0.03), branch]);
+	geometry.rotateZ(-Math.PI / 2);
+	return geometry;
+}
+
+const ITEMS = {
+	blade: { build: blade, stand: true, tilt: 16, cover: 2.2 },
+	tuft: { build: tuft, stand: true, tilt: 6, cover: 1.4 },
+	flower: { build: flower, stand: true, tilt: 10, cover: 1.4 },
+	leaf: { build: leaf, stand: false, tilt: 18, cover: 1.6 },
+	pebble: { build: pebble, stand: false, tilt: 20, cover: 1 },
+	twig: { build: twig, stand: false, tilt: 5, cover: 2 },
+};
+
+const built = new Map();
+
+/** The item's distinct vertices plus their reflections across x = 0, flat
+ * [x, y, z, ...]: what an item's fit is measured on, so a turned item fits by
+ * its real outline (not its looser box) and its mirrored twin fits too. */
+function outline(geometry) {
+	const position = geometry.getAttribute("position");
+	const seen = new Set(), points = [];
+	for (let i = 0; i < position.count; i += 1) {
+		const x = position.getX(i), y = position.getY(i), z = position.getZ(i);
+		for (const sx of [x, -x]) {
+			const key = `${sx},${y},${z}`;
+			if (!seen.has(key)) {
+				seen.add(key);
+				points.push(sx, y, z);
+			}
+		}
+	}
+	return Float64Array.from(points);
+}
+
+/** The item's cached template ({ geometry, points, stand, tilt, cover });
+ * clone the geometry before handing it to a mesh, which will dispose its own. */
+export function scatterItem(name) {
+	if (!built.has(name)) {
+		const geometry = ITEMS[name].build();
+		geometry.computeBoundingBox();
+		const { min, max } = geometry.boundingBox;
+		// Centred on x, standing on y = 0, a lying item centred on z too.
+		geometry.translate(-(min.x + max.x) / 2, -min.y, ITEMS[name].stand ? 0 : -(min.z + max.z) / 2);
+		geometry.computeVertexNormals();
+		geometry.computeBoundingBox();
+		geometry.computeBoundingSphere();
+		built.set(name, { ...ITEMS[name], geometry, points: outline(geometry) });
+	}
+	return built.get(name);
+}

package/src/sculpt-scatter-shape.js

@@ -0,0 +1,57 @@
+/**
+ * The scatter shape's recipe half (registered in sculpt-shapes.js): `count`
+ * small copies of one item, drawn as ONE instanced mesh by sculpt-scatter.js.
+ * A grass field built from hundreds of cone parts still looked sparse; as one
+ * scatter part it is thousands of blades and counts once toward maxParts
+ * (the whole recipe's items are capped by SCULPT_LIMITS.maxScatterItems).
+ *
+ *   item     blade | tuft | flower stand up; leaf | pebble | twig lie down
+ *   count    1..SCATTER_MAX_COUNT items
+ *   seed     picks another layout of the same items (default 0)
+ *   spread   "ground" (default): items stand on the bottom face of the size
+ *            box, anywhere in its x/z rectangle. Standing items are up to
+ *            size[1] tall; lying items are sized so `count` of them cover
+ *            the rectangle.
+ *            "shell": items sit on the ellipsoid inscribed in the size box,
+ *            facing outward (leaves on a tree crown, flowers on a bush),
+ *            sized so `count` of them cover it.
+ *
+ * Every item is fitted inside the size box. A mirrored copy draws its
+ * source's layout reflected (sculpt-scatter.js), so no `mirror` hook is needed.
+ * Pure: no three.js.
+ */
+
+import { readChoice, readInteger, readSeed } from "./sculpt-recipe-read.js";
+
+export const SCATTER_ITEMS = Object.freeze(["blade", "tuft", "flower", "leaf", "pebble", "twig"]);
+const SCATTER_SPREADS = ["ground", "shell"];
+const SCATTER_MAX_COUNT = 4000;
+
+/** Ground: the box the items fill. Shell: the ellipsoid they cover, as rings. */
+function scatterSamples(part) {
+	const [sx, sy, sz] = part.size.map((value) => value / 2);
+	const points = [];
+	if (part.spread === "ground") {
+		for (const x of [-sx, sx]) for (const y of [-sy, sy]) for (const z of [-sz, sz]) points.push([x, y, z]);
+		return [points];
+	}
+	for (let i = 0; i <= 16; i += 1) {
+		const polar = (i / 16) * Math.PI;
+		for (let j = 0; j < 24; j += 1) {
+			const t = (j / 24) * 2 * Math.PI;
+			points.push([Math.sin(polar) * Math.cos(t) * sx, Math.cos(polar) * sy, Math.sin(polar) * Math.sin(t) * sz]);
+		}
+	}
+	return [points];
+}
+
+export const SCATTER_SHAPE = {
+	keys: ["item", "count", "seed", "spread"],
+	read(raw, part, where) {
+		part.item = readChoice(raw.item, `${where}.item`, undefined, SCATTER_ITEMS);
+		part.count = readInteger(raw.count, `${where}.count`, undefined, 1, SCATTER_MAX_COUNT);
+		part.seed = readSeed(raw.seed, `${where}.seed`);
+		part.spread = readChoice(raw.spread, `${where}.spread`, "ground", SCATTER_SPREADS);
+	},
+	samples: scatterSamples,
+};

package/src/sculpt-scatter.js

@@ -0,0 +1,124 @@
+/**
+ * Scatter geometry: `count` copies of one small item (sculpt-scatter-items.js)
+ * as ONE InstancedMesh, laid out from the part's seed. The contract is in
+ * sculpt-scatter-shape.js.
+ *
+ * - Ground items take a low-discrepancy (R2) spread with a little jitter, so
+ *   a field is even without looking planted in rows.
+ * - Shell items take an area-uniform spread over the ellipsoid, leaning
+ *   further off its normal than ground items so a crown looks leafy, not scaly.
+ * - Every item is fitted inside the size box by its turned vertices: one that
+ *   would poke out is pulled in, one larger than the box is shrunk. The
+ *   record's measured box trusts size, so it holds.
+ * - A mirrored copy is seeded like its source and reflects each item's place
+ *   and turn (position x and the quaternion's y, z), so the pair is symmetric.
+ */
+
+import * as THREE from "three";
+import { scatterItem } from "./sculpt-scatter-items.js";
+import { isMirrorCopy, partSeed, seededRandom } from "./sculpt-noise.js";
+
+const UP = new THREE.Vector3(0, 1, 0);
+const SIDE = new THREE.Vector3(1, 0, 0);
+const DEG = Math.PI / 180;
+/** Extra lean on a shell, in degrees. */
+const SHELL_LEAN = 25;
+/** The R2 sequence's steps (1/g, 1/g² for the plastic number g). */
+const R2 = [0.7548776662466927, 0.5698402909980532];
+
+/** Surface area of an ellipsoid (Knud Thomsen, within about 1%). */
+function ellipsoidArea(a, b, c) {
+	const p = 1.6075;
+	return 4 * Math.PI * (((a * b) ** p + (a * c) ** p + (b * c) ** p) / 3) ** (1 / p);
+}
+
+/** A point on the ellipsoid with semi-axes `axes`, area-uniform, and its outward normal. */
+function shellPoint(axes, random, point, normal) {
+	const [a, b, c] = axes, least = Math.min(a, b, c);
+	for (let tries = 0; ; tries += 1) {
+		const y = random() * 2 - 1, angle = random() * 2 * Math.PI, r = Math.sqrt(1 - y * y);
+		const dx = r * Math.cos(angle), dz = r * Math.sin(angle);
+		normal.set(dx / a, y / b, dz / c);
+		// Stretching a sphere into an ellipsoid stretches area by |normal| · abc; keep points in proportion.
+		if (random() <= normal.length() * least || tries >= 32) {
+			point.set(dx * a, y * b, dz * c);
+			normal.normalize();
+			return;
+		}
+	}
+}
+
+/** The box (low, high per axis) of `points` turned by `q` and scaled, around the item's origin. */
+function turnedExtent(points, q, scale, low, high) {
+	low.fill(Infinity);
+	high.fill(-Infinity);
+	// Quaternion rotation written out: this runs for every vertex of every item.
+	const { x: qx, y: qy, z: qz, w: qw } = q;
+	for (let i = 0; i < points.length; i += 3) {
+		const x = points[i], y = points[i + 1], z = points[i + 2];
+		const tx = 2 * (qy * z - qz * y), ty = 2 * (qz * x - qx * z), tz = 2 * (qx * y - qy * x);
+		const rx = (x + qw * tx + qy * tz - qz * ty) * scale, ry = (y + qw * ty + qz * tx - qx * tz) * scale, rz = (z + qw * tz + qx * ty - qy * tx) * scale;
+		if (rx < low[0]) low[0] = rx;
+		if (rx > high[0]) high[0] = rx;
+		if (ry < low[1]) low[1] = ry;
+		if (ry > high[1]) high[1] = ry;
+		if (rz < low[2]) low[2] = rz;
+		if (rz > high[2]) high[2] = rz;
+	}
+}
+
+export function scatterMesh(part, material) {
+	const item = scatterItem(part.item);
+	const mesh = new THREE.InstancedMesh(item.geometry.clone(), material, part.count);
+	const half = part.size.map((value) => value / 2);
+	const random = seededRandom(partSeed(part, part.seed));
+	const shell = part.spread === "shell";
+	const { min, max } = item.geometry.boundingBox;
+	const height = max.y - min.y, length = Math.max(max.x - min.x, max.z - min.z);
+	const points = item.points;
+	const spacing = Math.sqrt((shell ? ellipsoidArea(...half) : part.size[0] * part.size[2]) / part.count);
+	const nominal = !shell && item.stand ? part.size[1] / height : (item.cover * spacing) / (item.stand ? height : length);
+	const lean = (item.tilt + (shell ? SHELL_LEAN : 0)) * DEG;
+	// Shell anchors sit inside the ellipsoid by about an item's outward reach, so the items end near its surface.
+	const outward = nominal * (item.stand ? height : height + 0.5 * length * Math.sin(lean)) * 0.85;
+	const axes = half.map((h) => Math.max(h - outward, h * 0.35));
+	const start = [random(), random()], jitter = 0.35 / Math.sqrt(part.count);
+	const point = new THREE.Vector3(), up = new THREE.Vector3();
+	const tilt = new THREE.Quaternion(), spin = new THREE.Quaternion(), turn = new THREE.Quaternion();
+	const matrix = new THREE.Matrix4(), scaled = new THREE.Vector3();
+	const low = [0, 0, 0], high = [0, 0, 0], bounds = new THREE.Box3();
+	for (let i = 0; i < part.count; i += 1) {
+		if (shell) shellPoint(axes, random, point, up);
+		else {
+			const u = (start[0] + i * R2[0]) % 1 + (random() - 0.5) * jitter, v = (start[1] + i * R2[1]) % 1 + (random() - 0.5) * jitter;
+			point.set((u - 0.5) * part.size[0], -half[1], (v - 0.5) * part.size[2]);
+			up.copy(UP);
+		}
+		let scale = nominal * (0.6 + 0.4 * random());
+		spin.setFromAxisAngle(UP, random() * 2 * Math.PI);
+		tilt.setFromAxisAngle(SIDE, random() * lean);
+		turn.setFromUnitVectors(UP, up).multiply(tilt).multiply(spin);
+		turnedExtent(points, turn, scale, low, high);
+		const fit = Math.min(1, ...half.map((h, axis) => (2 * h * 0.999) / (high[axis] - low[axis])));
+		scale *= fit;
+		for (let axis = 0; axis < 3; axis += 1) {
+			const lo = low[axis] * fit, hi = high[axis] * fit;
+			// Ground items stand on the bottom face; everything else is pulled inside the box.
+			const value = !shell && axis === 1 ? -half[1] - lo : THREE.MathUtils.clamp(point.getComponent(axis), -half[axis] - lo, half[axis] - hi);
+			point.setComponent(axis, value);
+			bounds.min.setComponent(axis, Math.min(bounds.min.getComponent(axis), value + lo));
+			bounds.max.setComponent(axis, Math.max(bounds.max.getComponent(axis), value + hi));
+		}
+		if (isMirrorCopy(part)) {
+			point.x = -point.x;
+			turn.set(turn.x, -turn.y, -turn.z, turn.w);
+		}
+		mesh.setMatrixAt(i, matrix.compose(point, turn, scaled.setScalar(scale)));
+	}
+	mesh.instanceMatrix.needsUpdate = true;
+	// The fitted outline, not three's box-of-boxes (which turns each item's box and overshoots size).
+	if (isMirrorCopy(part)) [bounds.min.x, bounds.max.x] = [-bounds.max.x, -bounds.min.x];
+	mesh.boundingBox = bounds;
+	mesh.boundingSphere = bounds.getBoundingSphere(new THREE.Sphere());
+	return mesh;
+}