@call-me-sensei/toonlab 0.1.1

package/src/debrisgen/debrisPalettes.js

@@ -0,0 +1,71 @@
+// Curated three-tone palettes (primary base / secondary mid / accent
+// highlight-or-detail) per debris family — one-click combinations that
+// read well under the toon shader, mirroring Tree Lab's leaf palettes.
+// Values are linear 0-1 RGB triplets matching surface.*Color.
+
+const palette = (id, label, primaryColor, secondaryColor, accentColor) => Object.freeze({
+  accentColor: Object.freeze(accentColor),
+  id,
+  label,
+  primaryColor: Object.freeze(primaryColor),
+  secondaryColor: Object.freeze(secondaryColor),
+});
+
+export const DEBRIS_PALETTES = Object.freeze({
+  ash: Object.freeze([
+    palette('cold-ash', 'Cold ash', [0.035, 0.03, 0.025], [0.16, 0.15, 0.14], [0.55, 0.06, 0.01]),
+    palette('warm-embers', 'Warm embers', [0.05, 0.03, 0.02], [0.2, 0.16, 0.13], [0.85, 0.28, 0.04]),
+    palette('white-ash', 'White ash', [0.22, 0.21, 0.2], [0.42, 0.41, 0.39], [0.65, 0.6, 0.52]),
+    palette('sawdust', 'Fresh sawdust', [0.58, 0.47, 0.32], [0.78, 0.66, 0.47], [0.55, 0.4, 0.24]),
+    palette('volcanic', 'Volcanic', [0.06, 0.05, 0.06], [0.18, 0.16, 0.18], [0.9, 0.35, 0.12]),
+  ]),
+  bone: Object.freeze([
+    palette('bleached', 'Bleached ivory', [0.78, 0.71, 0.56], [0.93, 0.87, 0.7], [0.42, 0.31, 0.19]),
+    palette('aged-tan', 'Aged tan', [0.62, 0.52, 0.38], [0.8, 0.7, 0.52], [0.34, 0.24, 0.15]),
+    palette('fossil', 'Fossil brown', [0.42, 0.33, 0.24], [0.6, 0.5, 0.38], [0.24, 0.18, 0.12]),
+    palette('museum', 'Museum white', [0.85, 0.83, 0.78], [0.96, 0.95, 0.9], [0.55, 0.5, 0.42]),
+    palette('swamp-bone', 'Swamp stained', [0.45, 0.44, 0.3], [0.66, 0.63, 0.44], [0.25, 0.26, 0.14]),
+  ]),
+  metal: Object.freeze([
+    palette('steel-rust', 'Steel & rust', [0.25, 0.31, 0.32], [0.49, 0.54, 0.52], [0.72, 0.26, 0.08]),
+    palette('galvanized', 'Galvanized', [0.36, 0.42, 0.45], [0.62, 0.68, 0.7], [0.3, 0.34, 0.38]),
+    palette('painted-red', 'Painted red', [0.5, 0.12, 0.08], [0.72, 0.24, 0.16], [0.32, 0.36, 0.38]),
+    palette('copper', 'Copper verdigris', [0.45, 0.26, 0.15], [0.68, 0.42, 0.25], [0.2, 0.55, 0.45]),
+    palette('gunmetal', 'Gunmetal', [0.12, 0.13, 0.16], [0.3, 0.32, 0.36], [0.55, 0.45, 0.2]),
+  ]),
+  organic: Object.freeze([
+    palette('autumn', 'Autumn litter', [0.34, 0.18, 0.05], [0.64, 0.43, 0.12], [0.66, 0.23, 0.06]),
+    palette('fresh-fall', 'Fresh fall', [0.25, 0.3, 0.08], [0.55, 0.52, 0.14], [0.72, 0.4, 0.08]),
+    palette('dried', 'Sun dried', [0.42, 0.32, 0.18], [0.66, 0.55, 0.34], [0.5, 0.3, 0.12]),
+    palette('shoreline', 'Shoreline', [0.68, 0.58, 0.48], [0.92, 0.81, 0.67], [0.79, 0.46, 0.39]),
+    palette('deep-forest', 'Deep forest', [0.12, 0.16, 0.07], [0.3, 0.34, 0.14], [0.5, 0.36, 0.1]),
+  ]),
+  stone: Object.freeze([
+    palette('concrete', 'Concrete', [0.39, 0.4, 0.38], [0.58, 0.56, 0.51], [0.53, 0.3, 0.19]),
+    palette('red-brick', 'Red brick', [0.45, 0.18, 0.11], [0.68, 0.31, 0.18], [0.32, 0.19, 0.14]),
+    palette('slate', 'Slate blue', [0.12, 0.16, 0.18], [0.3, 0.36, 0.38], [0.2, 0.25, 0.26]),
+    palette('sandstone', 'Sandstone', [0.55, 0.42, 0.27], [0.76, 0.62, 0.42], [0.42, 0.28, 0.16]),
+    palette('basalt', 'Basalt', [0.08, 0.08, 0.09], [0.22, 0.22, 0.24], [0.4, 0.38, 0.35]),
+    palette('mossy', 'Mossy stone', [0.3, 0.33, 0.28], [0.5, 0.52, 0.44], [0.28, 0.42, 0.2]),
+  ]),
+  wood: Object.freeze([
+    palette('bark-brown', 'Bark brown', [0.34, 0.2, 0.11], [0.55, 0.36, 0.2], [0.7, 0.46, 0.24]),
+    palette('bleached-drift', 'Bleached driftwood', [0.52, 0.43, 0.31], [0.78, 0.68, 0.5], [0.52, 0.39, 0.25]),
+    palette('silver-grey', 'Silvered grey', [0.38, 0.37, 0.34], [0.6, 0.58, 0.53], [0.45, 0.4, 0.33]),
+    palette('redwood', 'Redwood', [0.32, 0.12, 0.07], [0.55, 0.25, 0.13], [0.72, 0.4, 0.2]),
+    palette('charred', 'Charred', [0.06, 0.05, 0.045], [0.2, 0.17, 0.15], [0.5, 0.2, 0.06]),
+    palette('mossy-log', 'Mossy log', [0.22, 0.17, 0.1], [0.4, 0.34, 0.2], [0.3, 0.45, 0.18]),
+  ]),
+});
+
+function nearly(a, b) {
+  return Math.abs(a - b) < 0.012;
+}
+
+/** Finds the palette matching the current surface colors, if any. */
+export function matchDebrisPalette(type, surface) {
+  const palettes = DEBRIS_PALETTES[type] ?? [];
+  return palettes.find((entry) => ['primaryColor', 'secondaryColor', 'accentColor'].every(
+    (key) => entry[key].every((channel, index) => nearly(channel, surface[key][index])),
+  )) ?? null;
+}

package/src/debrisgen/debrisPhysics.js

@@ -0,0 +1,198 @@
+// Real-gravity settling for debris compositions. The generator's
+// deterministic placement gives each piece a near-rest starting pose;
+// this pass hands the pieces to Rapier (convex-hull colliders, gravity,
+// friction) and lets them fall, tumble, and slide until every body
+// sleeps — so piles, bundles, and scatters rest the way they would in
+// real life, with no interpenetration and no floaters. Runs in browser
+// and Node (rapier3d-compat inlines its WASM).
+
+import * as THREE from 'three';
+
+const MAX_STEPS = 300;
+const SLEEP_CHECK_EVERY = 20;
+// Every vertex goes into the hull: a sampled subset leaves mesh vertices
+// outside the collider, and once the body rotates during the sim those
+// vertices swing below the contact surface — pieces visually sink into
+// the ground. Rapier's quickhull chews through this budget in ~ms.
+const HULL_POINT_BUDGET = 30000;
+
+let rapierPromise = null;
+
+function getRapier() {
+  if (!rapierPromise) {
+    rapierPromise = import('@dimforge/rapier3d-compat').then(async (module) => {
+      const RAPIER = module.default ?? module;
+      await RAPIER.init();
+      return RAPIER;
+    });
+  }
+  return rapierPromise;
+}
+
+// One point cloud PER SUB-MESH, in the piece's body frame. A single hull
+// around a whole piece bridges concavities (a forked branch rides half a
+// unit up on the invisible envelope between its prongs); a compound body
+// with one hull per tube/cap/knot hugs the real shape.
+function collectMeshClouds(piece) {
+  const clouds = [];
+  const vertex = new THREE.Vector3();
+  const inverseRotation = piece.quaternion.clone().invert();
+  piece.traverse((mesh) => {
+    if (!mesh.isMesh) return;
+    const position = mesh.geometry.attributes.position;
+    if (!position || position.count < 4) return;
+    const stride = Math.max(1, Math.ceil(position.count / HULL_POINT_BUDGET));
+    const points = [];
+    for (let index = 0; index < position.count; index += stride) {
+      vertex
+        .fromBufferAttribute(position, index)
+        .applyMatrix4(mesh.matrixWorld)
+        .sub(piece.position)
+        .applyQuaternion(inverseRotation);
+      points.push(vertex.x, vertex.y, vertex.z);
+    }
+    if (points.length < 12) return;
+    // Merged meshes (Tree Lab branches, SDF skulls) are one concave
+    // geometry — slab-decompose along the longest axis so the hulls
+    // follow trunk and forks instead of bridging them.
+    for (const slab of splitCloudIntoSlabs(points)) clouds.push(slab);
+  });
+  return clouds;
+}
+
+function splitCloudIntoSlabs(points) {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let index = 0; index < points.length; index += 3) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis], points[index + axis]);
+      max[axis] = Math.max(max[axis], points[index + axis]);
+    }
+  }
+  const extents = [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
+  const longAxis = extents.indexOf(Math.max(...extents));
+  const sorted = [...extents].sort((a, b) => b - a);
+  const slabCount = Math.min(Math.max(Math.round(sorted[0] / Math.max(sorted[1], 1e-4)), 1), 8);
+  if (slabCount <= 1) return [new Float32Array(points)];
+  const buckets = Array.from({ length: slabCount }, () => []);
+  const span = extents[longAxis] || 1e-4;
+  for (let index = 0; index < points.length; index += 3) {
+    const t = (points[index + longAxis] - min[longAxis]) / span;
+    const bucket = Math.min(Math.floor(t * slabCount), slabCount - 1);
+    buckets[bucket].push(points[index], points[index + 1], points[index + 2]);
+  }
+  const slabs = buckets.filter((bucket) => bucket.length >= 12).map((bucket) => new Float32Array(bucket));
+  return slabs.length > 0 ? slabs : [new Float32Array(points)];
+}
+
+/**
+ * Simulates the asset's pieces under gravity and bakes the resting
+ * transforms. Deterministic for a given asset (fixed body order, fixed
+ * timestep). Skips ash/pile assets (mound geometry is its own ground).
+ */
+export async function settleDebrisPhysics(root, { maxSteps = MAX_STEPS } = {}) {
+  const recipe = root.userData.debrisRecipe;
+  // Single pieces settle too — a lone branch balances on real contact
+  // points only under real gravity.
+  if (!recipe || recipe.asset.type === 'ash' || root.children.length === 0) return root;
+
+  const RAPIER = await getRapier();
+  // Physics runs in unscaled space; rest poses are scale-invariant, so
+  // the asset scale is restored afterwards.
+  const savedScale = root.scale.x;
+  root.scale.setScalar(1);
+  root.updateMatrixWorld(true);
+
+  const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
+  world.createCollider(
+    RAPIER.ColliderDesc.cuboid(200, 1, 200).setTranslation(0, -1, 0).setFriction(0.9),
+  );
+
+  const bodies = [];
+  for (const piece of root.children) {
+    piece.updateMatrixWorld(true);
+    const clouds = collectMeshClouds(piece);
+    if (clouds.length === 0) continue;
+    const body = world.createRigidBody(
+      RAPIER.RigidBodyDesc.dynamic()
+        // Tiny lift relieves any initial interpenetration without a pop.
+        .setTranslation(piece.position.x, piece.position.y + 0.02, piece.position.z)
+        .setRotation({
+          w: piece.quaternion.w, x: piece.quaternion.x, y: piece.quaternion.y, z: piece.quaternion.z,
+        })
+        // Low angular damping: pieces caught mid-tip fall over to a truly
+        // stable face instead of freezing upright on an end cap.
+        .setLinearDamping(0.4)
+        .setAngularDamping(0.25),
+    );
+    let attached = 0;
+    for (const cloud of clouds) {
+      const colliderDesc = RAPIER.ColliderDesc.convexHull(cloud);
+      if (!colliderDesc) continue;
+      world.createCollider(colliderDesc.setFriction(0.85).setRestitution(0.02), body);
+      attached += 1;
+    }
+    if (attached === 0) {
+      const bounds = new THREE.Box3().setFromObject(piece, true);
+      const size = bounds.getSize(new THREE.Vector3());
+      world.createCollider(
+        RAPIER.ColliderDesc.cuboid(
+          Math.max(size.x / 2, 0.01), Math.max(size.y / 2, 0.01), Math.max(size.z / 2, 0.01),
+        ).setFriction(0.85).setRestitution(0.02),
+        body,
+      );
+    }
+    bodies.push({ body, piece });
+  }
+
+  world.timestep = 1 / 60;
+  const run = (steps) => {
+    for (let step = 0; step < steps; step += 1) {
+      world.step();
+      if (step % SLEEP_CHECK_EVERY === SLEEP_CHECK_EVERY - 1
+        && bodies.every(({ body }) => body.isSleeping())) break;
+    }
+  };
+  const bake = () => {
+    for (const { body, piece } of bodies) {
+      const translation = body.translation();
+      const rotation = body.rotation();
+      piece.position.set(translation.x, translation.y, translation.z);
+      piece.quaternion.set(rotation.x, rotation.y, rotation.z, rotation.w);
+      piece.updateMatrixWorld(true);
+    }
+  };
+
+  run(maxSteps);
+  bake();
+
+  // Balanced-on-end poses (a log standing on its sawn face) are stable
+  // under pure gravity but almost never occur with real thrown debris —
+  // pieces arrive with momentum. Detect anything resting taller than
+  // wide, give it a deterministic tip-over impulse, and settle again.
+  const bounds = new THREE.Box3();
+  for (let round = 0; round < 3; round += 1) {
+    const standing = bodies.filter(({ piece }) => {
+      bounds.setFromObject(piece, true);
+      const height = bounds.max.y - bounds.min.y;
+      const footprint = Math.max(bounds.max.x - bounds.min.x, bounds.max.z - bounds.min.z);
+      return height > footprint * 1.25;
+    });
+    if (standing.length === 0) break;
+    for (const [index, { body }] of standing.entries()) {
+      body.wakeUp();
+      // Strong deterministic shove, direction varied per round so a piece
+      // wedged against neighbours eventually finds a way down.
+      const magnitude = body.mass() * (0.45 + round * 0.3);
+      const flip = (index + round) % 2 === 0 ? 1 : -1;
+      body.applyTorqueImpulse({ x: magnitude * flip, y: 0, z: magnitude * 0.5 * -flip }, true);
+    }
+    run(220);
+    bake();
+  }
+  world.free();
+
+  root.scale.setScalar(savedScale);
+  root.updateMatrixWorld(true);
+  return root;
+}

package/src/debrisgen/debrisPresets.js

@@ -0,0 +1,155 @@
+import { createDebrisSettings } from './debrisSettings.js';
+
+function preset(id, label, type, variant, description, overrides = {}) {
+  return Object.freeze({
+    description,
+    id,
+    label,
+    settings: createDebrisSettings({
+      ...overrides,
+      asset: { ...(overrides.asset ?? {}), type, variant },
+    }),
+    type,
+    variant,
+  });
+}
+
+export const BUILT_IN_DEBRIS_PRESETS = Object.freeze([
+  preset('bleached-driftwood', 'Bleached driftwood', 'wood', 'driftwood', 'Salt-worn pale wood with broken fibers.', {
+    asset: { count: 1, seed: 7301, spread: 0 },
+    shape: { branchiness: 0.38, crookedness: 0.86, length: 3.05, splinters: 0.8, thickness: 0.23 },
+    surface: { accentColor: [0.52, 0.39, 0.25], primaryColor: [0.52, 0.43, 0.31], secondaryColor: [0.78, 0.68, 0.5], variation: 0.24 },
+  }),
+  preset('forest-branch', 'Forest branch', 'wood', 'branch', 'Bark-dark fallen limb with secondary twigs.', {
+    asset: { count: 1, seed: 4407, spread: 0 },
+    shape: { branchiness: 0.74, crookedness: 0.5, length: 3.2, splinters: 0.38, thickness: 0.25 },
+    surface: { accentColor: [0.38, 0.16, 0.045], primaryColor: [0.12, 0.055, 0.018], secondaryColor: [0.28, 0.13, 0.045], variation: 0.16 },
+  }),
+  preset('dry-twig-pile', 'Dry twig pile', 'wood', 'twigPile', 'A light scatter of snapped dry sticks.', {
+    asset: { count: 12, seed: 991, spread: 1.25 },
+    shape: { branchiness: 0.18, crookedness: 0.58, length: 0.92, splinters: 0.62, thickness: 0.055 },
+    surface: { accentColor: [0.42, 0.2, 0.07], primaryColor: [0.16, 0.07, 0.02], secondaryColor: [0.35, 0.17, 0.055] },
+  }),
+  preset('weathered-leg-bones', 'Weathered long bones', 'bone', 'longBone', 'Sun-bleached animal bones with enlarged joints.', {
+    asset: { count: 5, seed: 2204, spread: 1.35 },
+    shape: { curvature: 0.24, damage: 0.48, jointSize: 1.32, length: 1.18, thickness: 0.1 },
+  }),
+  preset('small-animal-skull', 'Small animal skull', 'bone', 'skull', 'Stylized cranium, sockets, snout, and broken jaw.', {
+    asset: { count: 1, seed: 8764, spread: 0 },
+    shape: { curvature: 0.2, damage: 0.62, jointSize: 1.08, length: 1.4, thickness: 0.16 },
+  }),
+  preset('herbivore-jaw', 'Herbivore jaw bones', 'bone', 'jawBone', 'Half jaws with molar rows and a bare diastema.', {
+    asset: { count: 3, seed: 4152, spread: 1.05 },
+    shape: { curvature: 0.4, damage: 0.35, jointSize: 1.1, length: 1.5, thickness: 0.11 },
+  }),
+  preset('shed-antlers', 'Shed antlers', 'bone', 'antler', 'Curving antler beams with forked tines.', {
+    asset: { count: 2, seed: 6108, spread: 1.1 },
+    shape: { curvature: 0.76, damage: 0.22, jointSize: 0.92, length: 1.85, thickness: 0.095 },
+  }),
+  preset('concrete-rubble', 'Concrete rubble', 'stone', 'rubble', 'Angular construction chunks with dusty variation.', {
+    asset: { count: 13, seed: 3041, spread: 1.55 },
+    shape: { brickRatio: 0.12, chunkSize: 0.48, detail: 0.72, sharpness: 0.8, stacking: 0.45 },
+  }),
+  preset('broken-red-bricks', 'Broken red bricks', 'stone', 'bricks', 'Recognizable brick fragments mixed with chips.', {
+    asset: { count: 11, seed: 8211, spread: 1.45 },
+    shape: { brickRatio: 0.92, chunkSize: 0.52, detail: 0.7, sharpness: 0.92, stacking: 0.42 },
+    surface: { accentColor: [0.32, 0.19, 0.14], primaryColor: [0.45, 0.18, 0.11], secondaryColor: [0.68, 0.31, 0.18] },
+  }),
+  preset('slate-shards', 'Slate shards', 'stone', 'shards', 'Thin sharp fragments with cool stone tones.', {
+    asset: { count: 17, seed: 1517, spread: 1.6 },
+    shape: { brickRatio: 0, chunkSize: 0.38, detail: 0.86, sharpness: 0.95, stacking: 0.28 },
+    surface: { accentColor: [0.2, 0.25, 0.26], primaryColor: [0.12, 0.16, 0.18], secondaryColor: [0.3, 0.36, 0.38] },
+  }),
+  preset('shattered-planks', 'Shattered planks', 'wood', 'planks', 'Snapped weathered boards with knotholes and warp.', {
+    asset: { count: 7, seed: 5217, spread: 1.4 },
+    shape: { branchiness: 0.6, crookedness: 0.55, length: 2.4, splinters: 0.7, thickness: 0.14 },
+    surface: { accentColor: [0.3, 0.24, 0.16], primaryColor: [0.42, 0.33, 0.22], secondaryColor: [0.6, 0.5, 0.35] },
+  }),
+  preset('firewood-logs', 'Firewood logs', 'wood', 'logs', 'Short sawn logs with pale cut ends and branch stubs.', {
+    asset: { count: 6, seed: 883, spread: 1.1 },
+    shape: { branchiness: 0.5, crookedness: 0.35, length: 1.6, splinters: 0.2, thickness: 0.18 },
+  }),
+  preset('gathered-sticks', 'Gathered stick bundle', 'wood', 'twigPile', 'A tied-together bunch of dry sticks.', {
+    asset: { arrangement: 'bundle', count: 14, messiness: 0.35, seed: 4471, spread: 0.5 },
+    shape: { branchiness: 0.12, crookedness: 0.4, kinks: 0.35, length: 1.3, splinters: 0.5, thickness: 0.05 },
+  }),
+  preset('dead-root-stump', 'Dead root stump', 'wood', 'rootStump', 'Weathered root ball with twisting dead roots.', {
+    asset: { count: 1, seed: 9925, spread: 0 },
+    shape: { barkStripped: 0.75, branchiness: 0.7, crookedness: 0.8, kinks: 0.55, length: 2.2, splinters: 0.3, thickness: 0.14 },
+    surface: { accentColor: [0.72, 0.65, 0.52], primaryColor: [0.3, 0.24, 0.17], secondaryColor: [0.52, 0.45, 0.34] },
+  }),
+  preset('bark-chip-litter', 'Bark chip litter', 'wood', 'barkChips', 'Curled bark flakes, dark outside and pale inside.', {
+    asset: { arrangement: 'patch', count: 20, seed: 2210, spread: 1.5 },
+    shape: { length: 1.4, thickness: 0.12 },
+  }),
+  preset('log-pile', 'Log pile', 'wood', 'logs', 'Firewood heaped into a loose stack.', {
+    asset: { arrangement: 'heap', count: 9, messiness: 0.4, seed: 5150, spread: 1.3 },
+    shape: { branchiness: 0.4, crookedness: 0.3, length: 1.5, splinters: 0.2, thickness: 0.17 },
+  }),
+  preset('sawdust-heap', 'Sawdust heap', 'ash', 'sawdust', 'Fresh pale sawdust with embedded slivers.', {
+    asset: { count: 8, seed: 7302, spread: 0.55 },
+    shape: { charcoal: 0.3, embers: 0, footprint: 1.2, moundHeight: 0.34, rim: 0.15 },
+    surface: { accentColor: [0.55, 0.4, 0.24], primaryColor: [0.58, 0.47, 0.32], secondaryColor: [0.78, 0.66, 0.47] },
+  }),
+  preset('river-pebbles', 'River pebbles', 'stone', 'riverstones', 'Smooth flat skipping stones in cool greys.', {
+    asset: { count: 15, seed: 3320, spread: 1.35 },
+    shape: { banding: 0.3, chunkSize: 0.26, detail: 0.35, flatness: 0.7, sharpness: 0.1 },
+  }),
+  preset('obsidian-shards', 'Obsidian shards', 'stone', 'obsidian', 'Glassy tapered fragments with conchoidal ridges.', {
+    asset: { count: 9, seed: 6644, spread: 1.2 },
+    shape: { banding: 0.7, chunkSize: 0.3, detail: 0.55, flatness: 0.25, sharpness: 0.85 },
+    surface: { accentColor: [0.16, 0.13, 0.22], primaryColor: [0.05, 0.05, 0.07], secondaryColor: [0.18, 0.19, 0.24] },
+  }),
+  preset('meteorite-fall', 'Meteorite fall', 'stone', 'meteor', 'Cratered pitted stones with a scorched crust.', {
+    asset: { count: 5, seed: 7811, spread: 1.3 },
+    shape: { banding: 0.1, chunkSize: 0.42, detail: 0.8, flatness: 0.15, sharpness: 0.2 },
+    surface: { accentColor: [0.45, 0.2, 0.08], primaryColor: [0.1, 0.09, 0.09], secondaryColor: [0.24, 0.21, 0.19] },
+  }),
+  preset('rough-gems', 'Rough gems', 'stone', 'gems', 'Faceted uncut crystals with beveled edges.', {
+    asset: { count: 8, seed: 1092, spread: 1.05 },
+    shape: { banding: 0.5, chunkSize: 0.2, detail: 0.15, flatness: 0.1, sharpness: 0.75 },
+    surface: { accentColor: [0.16, 0.5, 0.55], primaryColor: [0.1, 0.26, 0.36], secondaryColor: [0.36, 0.68, 0.72] },
+  }),
+  preset('rusted-sheet-metal', 'Rusted sheet metal', 'metal', 'sheets', 'Bent, corrugated sheets with oxidized edges.', {
+    asset: { count: 5, seed: 5604, spread: 1.35 },
+    shape: { bend: 0.82, corrugation: 0.62, rust: 0.82, sheetSize: 1.05, wireChance: 0.08 },
+  }),
+  preset('crushed-cans', 'Crushed cans', 'metal', 'cans', 'Low-sided dented cans scattered on the ground.', {
+    asset: { count: 9, seed: 773, spread: 1.45 },
+    shape: { bend: 0.74, corrugation: 0.16, rust: 0.34, sheetSize: 0.48, wireChance: 0 },
+    surface: { accentColor: [0.8, 0.25, 0.07], primaryColor: [0.3, 0.42, 0.45], secondaryColor: [0.7, 0.78, 0.74] },
+  }),
+  preset('workshop-scrap', 'Workshop scrap', 'metal', 'scrapPile', 'Mixed plates, pipes, cans, and curled wire.', {
+    asset: { count: 12, seed: 4690, spread: 1.5 },
+    shape: { bend: 0.66, corrugation: 0.28, rust: 0.7, sheetSize: 0.62, wireChance: 0.62 },
+  }),
+  preset('autumn-leaf-litter', 'Autumn leaf litter', 'organic', 'leafLitter', 'A broad scatter of curled dry leaves.', {
+    asset: { count: 28, seed: 9318, spread: 1.8 },
+    shape: { coneRatio: 0.12, coverage: 1.45, curl: 0.66, dryness: 0.9, leafSize: 0.22 },
+  }),
+  preset('forest-pinecones', 'Forest pinecones', 'organic', 'pinecones', 'Layered cones with a few needles and husks.', {
+    asset: { count: 10, seed: 3008, spread: 1.4 },
+    shape: { coneRatio: 0.9, coverage: 0.85, curl: 0.24, dryness: 0.68, leafSize: 0.38 },
+  }),
+  preset('shoreline-shells', 'Shoreline shells', 'organic', 'shells', 'Fan shells and worn spiral fragments.', {
+    asset: { count: 13, seed: 1182, spread: 1.55 },
+    shape: { coneRatio: 0.45, coverage: 0.92, curl: 0.4, dryness: 0.5, leafSize: 0.3 },
+    surface: { accentColor: [0.79, 0.46, 0.39], primaryColor: [0.68, 0.58, 0.48], secondaryColor: [0.92, 0.81, 0.67] },
+  }),
+  preset('cold-ash-pile', 'Cold ash pile', 'ash', 'ashPile', 'A soft grey mound with scattered black remains.', {
+    asset: { count: 14, seed: 6721, spread: 0.65 },
+    shape: { charcoal: 0.38, embers: 0, footprint: 1.5, moundHeight: 0.32, rim: 0.36 },
+  }),
+  preset('spent-campfire', 'Spent campfire', 'ash', 'campfire', 'Charred crossed wood, ash, and a faint ember accent.', {
+    asset: { count: 10, seed: 2026, spread: 0.5 },
+    shape: { charcoal: 0.76, embers: 0.18, footprint: 1.65, moundHeight: 0.24, rim: 0.68 },
+  }),
+  preset('charcoal-scatter', 'Charcoal scatter', 'ash', 'charcoal', 'Cracked black fuel pieces and powder.', {
+    asset: { count: 18, seed: 8146, spread: 1.15 },
+    shape: { charcoal: 0.94, embers: 0.04, footprint: 1.25, moundHeight: 0.12, rim: 0.2 },
+  }),
+]);
+
+export function findDebrisPreset(id) {
+  return BUILT_IN_DEBRIS_PRESETS.find((entry) => entry.id === id) ?? null;
+}