@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/propgen/propAsset.js

@@ -0,0 +1,323 @@
+// The PropAsset contract — the ONE shape every placeable thing reduces to,
+// procedural or imported. This is the strategic seam of the library: the
+// placement pipeline (propPlacement.js), buildings, villages, the catalog,
+// and the pro asset faucet all traffic exclusively in PropAssets.
+//
+//   asset.build(seed?) → {
+//     object3D,   // origin at ground contact, +y up
+//     footprint,  // { radius } | { circles: [{x, z, radius}] } — feeds
+//                 //   world.collision.addCircles verbatim (local frame)
+//     anchor,     // ground-contact offset: final y = heightAt(x, z) + anchor
+//     lod,        // optional { far: object3D, distance }
+//   }
+//
+// Linear assets (fences, walls) additionally implement
+// `buildAlong(points3D)` — they are generated continuously along a line,
+// not instanced — and placeAlongSpline dispatches on that automatically.
+
+import * as THREE from 'three';
+
+import { getDebrisDetailTexture } from '../debrisgen/debrisTextures.js';
+import { createPropRandom } from './propParts.js';
+import {
+  PROP_TYPES,
+  createPropSettings,
+  validatePropRecipeDocument,
+} from './propSettings.js';
+import {
+  generateFenceAlong,
+  generateLantern,
+  generateMilestone,
+  generateSignpost,
+  generateStoneStairs,
+} from './generatorsWave1.js';
+import {
+  generateBench,
+  generateCrateStack,
+  generateFirewood,
+  generatePier,
+  generateStoneWallAlong,
+  generateTorii,
+  generateWell,
+} from './generatorsWave2.js';
+
+const POINT_GENERATORS = {
+  bench: generateBench,
+  crateStack: generateCrateStack,
+  firewood: generateFirewood,
+  lantern: generateLantern,
+  milestone: generateMilestone,
+  pier: generatePier,
+  signpost: generateSignpost,
+  stoneStairs: generateStoneStairs,
+  torii: generateTorii,
+  well: generateWell,
+};
+
+const LINEAR_GENERATORS = {
+  fence: generateFenceAlong,
+  stoneWall: generateStoneWallAlong,
+};
+
+// Which procedural detail map suits each type (multiplies vertex colors,
+// same texture cache debrisgen uses — no new texture systems).
+const TEXTURE_FAMILY = {
+  bench: { kind: 'wood', style: 'grain' },
+  crateStack: { kind: 'wood', style: 'grain' },
+  fence: { kind: 'wood', style: 'grain' },
+  firewood: { kind: 'wood', style: 'bark' },
+  lantern: { kind: 'stone', style: 'speckle' },
+  milestone: { kind: 'stone', style: 'speckle' },
+  pier: { kind: 'wood', style: 'grain' },
+  signpost: { kind: 'wood', style: 'grain' },
+  stoneStairs: { kind: 'stone', style: 'speckle' },
+  stoneWall: { kind: 'stone', style: 'speckle' },
+  torii: { kind: 'wood', style: 'grain' },
+  well: { kind: 'stone', style: 'speckle' },
+};
+
+// LOD swap distance per type: bigger silhouettes hold detail longer.
+const LOD_DISTANCE = {
+  bench: 40,
+  crateStack: 50,
+  fence: 70,
+  firewood: 45,
+  lantern: 55,
+  milestone: 45,
+  pier: 90,
+  signpost: 50,
+  stoneStairs: 60,
+  stoneWall: 70,
+  torii: 120,
+  well: 80,
+};
+
+function createPropMaterials(settings) {
+  const family = TEXTURE_FAMILY[settings.asset.type] ?? { kind: 'stone', style: 'speckle' };
+  const main = new THREE.MeshStandardMaterial({
+    map: getDebrisDetailTexture(family.kind, settings.asset.seed, family.style, 1),
+    metalness: 0,
+    roughness: settings.surface.roughness,
+    vertexColors: true,
+  });
+  main.name = `Prop ${settings.asset.type}`;
+  main.userData.envRole = 'standard';
+
+  // Warm unlit lamp bodies: emissive carries the glow through the toon
+  // conversion and into GLB exports.
+  const glow = new THREE.MeshStandardMaterial({
+    emissive: new THREE.Color(1, 0.72, 0.32),
+    emissiveIntensity: 0.85,
+    metalness: 0,
+    roughness: 0.6,
+    vertexColors: true,
+  });
+  glow.name = `Prop ${settings.asset.type} glow`;
+  glow.userData.envRole = 'emissive';
+  return { glow, main };
+}
+
+function assembleGroup(settings, result, materials, detail) {
+  const group = new THREE.Group();
+  group.name = `Prop ${settings.asset.type} ${settings.asset.variant}${detail === 'lo' ? ' (lo)' : ''}`;
+  if (result.main) {
+    const mesh = new THREE.Mesh(result.main, materials.main);
+    mesh.name = 'PropBody';
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    group.add(mesh);
+  }
+  if (result.glow) {
+    const mesh = new THREE.Mesh(result.glow, materials.glow);
+    mesh.name = 'PropGlow';
+    mesh.castShadow = false; // lamp cores are light sources, not occluders
+    mesh.receiveShadow = false;
+    group.add(mesh);
+  }
+  if (settings.asset.scale !== 1) group.scale.setScalar(settings.asset.scale);
+  return group;
+}
+
+function scaleFootprint(footprint, scale) {
+  if (!footprint || scale === 1) return footprint;
+  if (footprint.circles) {
+    return {
+      circles: footprint.circles.map((circle) => ({
+        radius: circle.radius * scale,
+        x: circle.x * scale,
+        z: circle.z * scale,
+      })),
+    };
+  }
+  return { radius: (footprint.radius ?? 0.3) * scale };
+}
+
+/**
+ * Builds one prop object (no asset wrapper) — the direct construction path
+ * labs and quick scripts use. Returns `{ object3D, footprint, anchor, stats }`.
+ */
+export function buildProp(settingsInput = {}, { detail = 'hi' } = {}) {
+  const settings = createPropSettings(settingsInput);
+  const type = settings.asset.type;
+  const generator = POINT_GENERATORS[type];
+  if (!generator) {
+    throw new Error(`Prop type "${type}" is linear — use buildPropAlong / placeAlongSpline.`);
+  }
+  const random = createPropRandom(settings.asset.seed);
+  const result = generator(settings, random, detail);
+  const materials = createPropMaterials(settings);
+  const object3D = assembleGroup(settings, result, materials, detail);
+  object3D.userData.propRecipe = settings;
+  let triangles = 0;
+  object3D.traverse((object) => {
+    if (object.isMesh && object.geometry.index) triangles += object.geometry.index.count / 3;
+  });
+  return {
+    anchor: 0,
+    footprint: scaleFootprint(result.footprint, settings.asset.scale),
+    object3D,
+    stats: { triangles: Math.round(triangles) },
+  };
+}
+
+/**
+ * Builds a linear prop run along resolved world-space points
+ * `[{x, y, z}, …]`. Returns `{ object3D, footprints }` — footprints are
+ * world-frame circles ready for `collision.addCircles`.
+ */
+export function buildPropAlong(settingsInput, points, { detail = 'hi' } = {}) {
+  const settings = createPropSettings(settingsInput);
+  const type = settings.asset.type;
+  const generator = LINEAR_GENERATORS[type];
+  if (!generator) {
+    throw new Error(`Prop type "${type}" is not linear — use buildProp / placeProps.`);
+  }
+  const random = createPropRandom(settings.asset.seed);
+  const result = generator(settings, random, points, detail);
+  const materials = createPropMaterials(settings);
+  const object3D = assembleGroup(settings, result, materials, detail);
+  object3D.userData.propRecipe = settings;
+  return { footprints: result.footprints, object3D };
+}
+
+/**
+ * Wraps generator settings into the PropAsset contract. `build(seed)`
+ * overrides only the seed (variants of one design); pass full settings to
+ * `createPropAsset` for anything more.
+ */
+export function createPropAsset(settingsInput = {}) {
+  const settings = createPropSettings(settingsInput);
+  const type = settings.asset.type;
+  const linear = Boolean(PROP_TYPES[type]?.linear);
+  const asset = {
+    linear,
+    settings,
+    type,
+    variant: settings.asset.variant,
+  };
+  if (linear) {
+    asset.buildAlong = (points, options = {}) => buildPropAlong(
+      { ...settings, asset: { ...settings.asset, seed: options.seed ?? settings.asset.seed } },
+      points,
+      options,
+    );
+    // Linear assets still expose a build() so thumbnails/labs can preview a
+    // short straight run without a spline.
+    asset.build = (seed = settings.asset.seed) => {
+      const points = [0, 1, 2].map((index) => ({ x: (index - 1) * 2.2, y: 0, z: 0 }));
+      const { object3D, footprints } = buildPropAlong(
+        { ...settings, asset: { ...settings.asset, seed } },
+        points,
+      );
+      return { anchor: 0, footprint: { circles: footprints }, object3D };
+    };
+    return asset;
+  }
+  asset.build = (seed = settings.asset.seed) => {
+    const buildSettings = { ...settings, asset: { ...settings.asset, seed } };
+    const hi = buildProp(buildSettings, { detail: 'hi' });
+    const lo = buildProp(buildSettings, { detail: 'lo' });
+    return {
+      anchor: hi.anchor,
+      footprint: hi.footprint,
+      lod: { distance: LOD_DISTANCE[type] ?? 55, far: lo.object3D },
+      object3D: hi.object3D,
+      stats: hi.stats,
+    };
+  };
+  return asset;
+}
+
+/**
+ * The OSS↔pro seam: wraps ANY Object3D (imported GLB, pro-generated, hand
+ * modeling) into the PropAsset contract so every pipeline downstream —
+ * scatter, spline placement, collision, catalog — takes it with zero extra
+ * work. Footprint and anchor are measured from the bounding box when not
+ * given.
+ */
+export function propAssetFromObject(object3D, {
+  footprint = null,
+  anchor = null,
+  lod = null,
+  name = null,
+} = {}) {
+  if (!object3D?.isObject3D) throw new Error('propAssetFromObject needs an Object3D.');
+  const box = new THREE.Box3().setFromObject(object3D);
+  const measuredAnchor = Number.isFinite(anchor) ? anchor : (box.isEmpty() ? 0 : -box.min.y);
+  let resolvedFootprint = footprint;
+  if (!resolvedFootprint) {
+    const sizeX = box.isEmpty() ? 0.6 : box.max.x - box.min.x;
+    const sizeZ = box.isEmpty() ? 0.6 : box.max.z - box.min.z;
+    resolvedFootprint = { radius: Math.max(Math.hypot(sizeX, sizeZ) * 0.32, 0.2) };
+  }
+  return {
+    build(/* seed ignored: imported meshes have one shape */) {
+      const clone = object3D.clone(true);
+      clone.traverse((child) => {
+        if (child.isMesh) {
+          child.castShadow = true;
+          child.receiveShadow = true;
+        }
+      });
+      return {
+        anchor: measuredAnchor,
+        footprint: resolvedFootprint,
+        lod: lod ?? null,
+        object3D: clone,
+      };
+    },
+    imported: true,
+    linear: false,
+    type: name ?? object3D.name ?? 'imported',
+    variant: 'imported',
+  };
+}
+
+/** Deterministic rebuild from a recipe document (throws on invalid input). */
+export function createPropFromRecipe(recipe, options = {}) {
+  const { ok, errors } = validatePropRecipeDocument(recipe);
+  if (!ok) throw new Error(`Invalid prop recipe: ${errors.join(' ')}`);
+  const type = recipe.settings.asset.type;
+  if (PROP_TYPES[type]?.linear) return createPropAsset(recipe.settings).build();
+  return buildProp(recipe.settings, options);
+}
+
+/** Recipe → PropAsset (what `catalog.spawn` returns for prop entries). */
+export function createPropAssetFromRecipe(recipe) {
+  const { ok, errors } = validatePropRecipeDocument(recipe);
+  if (!ok) throw new Error(`Invalid prop recipe: ${errors.join(' ')}`);
+  return createPropAsset(recipe.settings);
+}
+
+export function disposeProp(root) {
+  const materials = new Set();
+  root?.traverse((object) => {
+    if (!object.isMesh) return;
+    object.geometry?.dispose();
+    for (const material of Array.isArray(object.material) ? object.material : [object.material]) {
+      if (material) materials.add(material);
+    }
+  });
+  // Detail textures are cache-owned (shared across props) — never disposed here.
+  for (const material of materials) material.dispose?.();
+}

package/src/propgen/propParts.js

@@ -0,0 +1,170 @@
+// Tiny geometry kit the prop generators share. Every part is a primitive
+// (box / cylinder / lathe) transformed into place and vertex-painted from
+// the settings palette; a generator's output is ONE merged geometry per
+// material role (main + optional glow), which is what keeps a prop at 1–2
+// draw calls and makes instanced placement trivial.
+
+import * as THREE from 'three';
+
+import { createDebrisRandom } from '../debrisgen/debrisGenerator.js';
+
+const scratchMatrix = new THREE.Matrix4();
+const scratchQuaternion = new THREE.Quaternion();
+const scratchEuler = new THREE.Euler();
+const scratchPosition = new THREE.Vector3();
+const scratchScale = new THREE.Vector3();
+
+export { createDebrisRandom as createPropRandom };
+
+function paletteColor(surface, slot) {
+  const values = slot === 2 ? surface.accentColor
+    : slot === 1 ? surface.secondaryColor
+      : surface.primaryColor;
+  return values;
+}
+
+/**
+ * Collects transformed, painted primitives and merges them per role.
+ * Roles: 'main' (environment-shaded) and 'glow' (warm unlit lamp bodies).
+ *
+ * Two RNG streams: the generator's `random` drives STRUCTURE (placement
+ * jitter — must draw identically for hi and lo detail so LOD swaps don't
+ * rearrange the prop), while per-vertex paint drift uses `paintRandom`
+ * (vertex counts differ between LODs, so it must not share the stream).
+ */
+export class PartsBuilder {
+  constructor(surface, random, paintRandom = null) {
+    this.surface = surface;
+    this.random = random;
+    // One structural draw seeds the paint stream — the same single draw on
+    // every detail level, so hi/lo geometry stays jitter-identical while
+    // per-vertex drift (whose call count differs by LOD) runs independently.
+    this.paintRandom = paintRandom ?? createDebrisRandom(Math.floor(random() * 0xffffffff));
+    this.parts = { glow: [], main: [] };
+  }
+
+  /**
+   * Adds a geometry. Options: position [x,y,z], rotation [rx,ry,rz] (YXZ),
+   * scale number|[x,y,z], slot 0|1|2 (palette), shade multiplier, role.
+   * The geometry is consumed (cloned by value into the merge lists).
+   */
+  add(geometry, {
+    position = [0, 0, 0],
+    rotation = [0, 0, 0],
+    scale = 1,
+    slot = 0,
+    shade = 1,
+    role = 'main',
+    flatShade = false,
+  } = {}) {
+    const scaleVec = Array.isArray(scale) ? scale : [scale, scale, scale];
+    scratchEuler.set(rotation[0], rotation[1], rotation[2], 'YXZ');
+    scratchQuaternion.setFromEuler(scratchEuler);
+    scratchPosition.set(position[0], position[1], position[2]);
+    scratchScale.set(scaleVec[0], scaleVec[1], scaleVec[2]);
+    scratchMatrix.compose(scratchPosition, scratchQuaternion, scratchScale);
+    geometry.applyMatrix4(scratchMatrix);
+    if (flatShade) geometry.computeVertexNormals();
+    this.paint(geometry, slot, shade);
+    this.parts[role in this.parts ? role : 'main'].push(geometry);
+    return this;
+  }
+
+  box(w, h, d, options = {}) {
+    return this.add(new THREE.BoxGeometry(w, h, d), options);
+  }
+
+  cylinder(radiusTop, radiusBottom, height, options = {}) {
+    const segments = options.segments ?? 10;
+    return this.add(
+      new THREE.CylinderGeometry(radiusTop, radiusBottom, height, segments),
+      options,
+    );
+  }
+
+  cone(radius, height, options = {}) {
+    const segments = options.segments ?? 10;
+    return this.add(new THREE.ConeGeometry(radius, height, segments), options);
+  }
+
+  sphere(radius, options = {}) {
+    const segments = options.segments ?? 8;
+    return this.add(new THREE.SphereGeometry(radius, segments, Math.max(6, segments - 2)), options);
+  }
+
+  /** Lathe from [ [radius, y], ... ] profile pairs (meters). */
+  lathe(profile, options = {}) {
+    const points = profile.map(([radius, y]) => new THREE.Vector2(radius, y));
+    const segments = options.segments ?? 10;
+    return this.add(new THREE.LatheGeometry(points, segments), options);
+  }
+
+  /** Baked vertex paint: palette slot × drift × upward edge light. */
+  paint(geometry, slot, shade) {
+    if (!geometry.attributes.normal) geometry.computeVertexNormals();
+    const { surface, paintRandom: random } = this;
+    const base = paletteColor(surface, slot);
+    const normal = geometry.attributes.normal;
+    const count = geometry.attributes.position.count;
+    const colors = new Float32Array(count * 3);
+    for (let index = 0; index < count; index += 1) {
+      const drift = 1 + (random() * 2 - 1) * surface.variation;
+      const upward = Math.max(0, normal.getY(index));
+      const edge = 1 + upward * surface.edgeLight * 0.3;
+      const value = drift * edge * shade;
+      colors[index * 3] = Math.min(base[0] * value, 1);
+      colors[index * 3 + 1] = Math.min(base[1] * value, 1);
+      colors[index * 3 + 2] = Math.min(base[2] * value, 1);
+    }
+    geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+    return geometry;
+  }
+
+  /** Merges collected parts: { main, glow } BufferGeometries (glow null when unused). */
+  build() {
+    return {
+      glow: mergePainted(this.parts.glow),
+      main: mergePainted(this.parts.main),
+    };
+  }
+}
+
+/** Position+normal+color+uv merge (uv optional per-part; missing uv fills 0). */
+export function mergePainted(geometries) {
+  if (!geometries.length) return null;
+  const positions = [];
+  const normals = [];
+  const uvs = [];
+  const colors = [];
+  const indices = [];
+  let offset = 0;
+  for (const geometry of geometries) {
+    const position = geometry.attributes.position;
+    const normal = geometry.attributes.normal;
+    const uv = geometry.attributes.uv;
+    const color = geometry.attributes.color;
+    for (let index = 0; index < position.count; index += 1) {
+      positions.push(position.getX(index), position.getY(index), position.getZ(index));
+      normals.push(normal.getX(index), normal.getY(index), normal.getZ(index));
+      uvs.push(uv ? uv.getX(index) : 0, uv ? uv.getY(index) : 0);
+      if (color) colors.push(color.getX(index), color.getY(index), color.getZ(index));
+      else colors.push(1, 1, 1);
+    }
+    if (geometry.index) {
+      for (let index = 0; index < geometry.index.count; index += 1) {
+        indices.push(geometry.index.getX(index) + offset);
+      }
+    } else {
+      for (let index = 0; index < position.count; index += 1) indices.push(index + offset);
+    }
+    offset += position.count;
+    geometry.dispose();
+  }
+  const merged = new THREE.BufferGeometry();
+  merged.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  merged.setAttribute('normal', new THREE.Float32BufferAttribute(normals, 3));
+  merged.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2));
+  merged.setAttribute('color', new THREE.Float32BufferAttribute(colors, 3));
+  merged.setIndex(indices);
+  return merged;
+}