Skip to content

You can now generate creatures directly within your project. Drop the open-source into your Agent, and start prompting what you want.

JavaScript
19.5 KB
Raw Blame
// ── the vertex-colour shading stack (L1–L8) ────────────────────────────────
//
// Ported from an interactive lab where every layer here was settled against six
// real creatures and every removed control was removed because it MEASURED as
// dead, not because it looked redundant. The numbers in DEFAULTS are that lab's
// final read-out.
//
// Two things are different here, and both are improvements the lab could not
// have made:
//
//   · CLASSIFICATION IS FREE. The lab worked on a finished GLB and had to GUESS
//     which parts were flesh and which were hardware, from bone counts. That
//     guess failed completely on two shipped creatures — the owl and the
//     some creatures classify as 100% hardware, so the whole stack skipped them. The
//     engine does not guess: the spec says what every piece IS. Volumes, hands
//     and paws are flesh; spikes, curves, membranes and fins are hardware; eyes
//     are features. `"shade"` on a volume or part overrides it, which is how a
//     trunk (a curve that is flesh) says so.
//
//   · THERE IS NO ORIGINAL COLOUR TO PRESERVE. The lab's L1 spent its effort
//     recovering per-vertex colour that step 0 of that pipeline had thrown away.
//     Here the arc bands ARE the colour, first-hand. What survives from L1 is
//     the half that was never about recovery: the cross-part spatial smoothing
//     that kills seams, because a colour field that is a function of POSITION
//     gives two coincident points the same value by construction.
//
// Everything below is a pure function of position and classification. No
// randomness, no dates — the same spec compiles to the same bytes.

// ── OKLab ──────────────────────────────────────────────────────────────────
// L is lightness, hypot(a,b) is chroma, and they are INDEPENDENT. That is the
// whole reason this stack works in OKLab and not in RGB: "brighter and more
// saturated" is two numbers here and is impossible in any blend mode, because
// every mode that brightens moves toward white and white has chroma 0.
function lin2oklab(c) {
  const l = Math.cbrt(0.4122214708 * c[0] + 0.5363325363 * c[1] + 0.0514459929 * c[2]);
  const m = Math.cbrt(0.2119034982 * c[0] + 0.6806995451 * c[1] + 0.1073969566 * c[2]);
  const s = Math.cbrt(0.0883024619 * c[0] + 0.2817188376 * c[1] + 0.6299787005 * c[2]);
  return [0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
          1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
          0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s];
}
function oklabToLinRaw(L) {
  const l = (L[0] + 0.3963377774 * L[1] + 0.2158037573 * L[2]) ** 3;
  const m = (L[0] - 0.1055613458 * L[1] - 0.0638541728 * L[2]) ** 3;
  const s = (L[0] - 0.0894841775 * L[1] - 1.2914855480 * L[2]) ** 3;
  return [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
          -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
          -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s];
}
function oklab2lin(L) {
  return oklabToLinRaw(L).map(v => (v < 0 ? 0 : v > 1 ? 1 : v));
}
function inGamut(c) {
  const r = oklabToLinRaw(c);
  return r.every(v => v >= -1e-4 && v <= 1.0001);
}

const ss = (a, b, x) => {
  const t = Math.max(0, Math.min(1, (x - a) / ((b - a) || 1e-9)));
  return t * t * (3 - 2 * t);
};
const mix = (a, b, t) => [a[0] + (b[0] - a[0]) * t,
                          a[1] + (b[1] - a[1]) * t,
                          a[2] + (b[2] - a[2]) * t];
const s2l = v => Math.pow(v, 2.2);
function hex2lab(h) {
  const x = String(h).replace('#', '');
  return lin2oklab([0, 2, 4].map(i => s2l(parseInt(x.substr(i, 2), 16) / 255)));
}

// ── settled values ─────────────────────────────────────────────────────────
const DEFAULTS = {
  seam:    { radius_edges: 3, min_frac: 0.030 },
  pattern: { color: null, sharpness: 0.45, amount: 1.00, scale: 0.06 },
  ramp:    { bottom: '#001370', mid: '#cfcfcf', top: '#fffcf0',
             p0: 0.00, pm: 0.31, wm: 0.08, p1: 1.00,
             sh0: 0.0, sh1: 0.0, chroma: 1.0, amount: 1.00 },
  boost:   { y0: 0.00, y1: 0.40, gamma: 0.30, dL: 0.03, dC: 1.50, amount: 1.00,
             target: 'all' },
  bleed:   { radius: 0.025, sharpness: 0.35, amount: 0.45 },
  hardsh:  { amount: 0.54, gamma: 0.70 },
  bodysh:  { lights: 4, rot: 4, elev: 17, amount: 0.20, gamma: 1.95 },
};

// ── classification ─────────────────────────────────────────────────────────
const HARD_TYPES = new Set(['spike', 'curve', 'membrane', 'fin']);
const FX_MATERIAL = /^(eye|pupil|iris|sclera|nose|nostril|tooth|teeth|tongue)/i;

function classOf(m, declared) {
  if (declared) return declared;                       // spec wins, always
  if (m.partType === 'eye' || FX_MATERIAL.test(m.material || '')) return 'fx';
  if (m.partType && HARD_TYPES.has(m.partType)) return 'hard';
  return 'flesh';                                      // volumes, hands, paws
}

/** Read `shade` off the spec for each mesh: per-part, then per-volume. */
function declaredClasses(spec) {
  const byName = new Map();
  for (const v of spec.volumes || []) if (v.shade) byName.set(v.chain, v.shade);
  for (const p of spec.parts || []) {
    if (!p.shade) continue;
    const label = p.name || `${p.type}@${p.host || 'ribs'}`;
    byName.set(label, p.shade);
    byName.set(label + '.R', p.shade);
  }
  return byName;
}

// ── spatial grid over a subset of vertices ─────────────────────────────────
// Used twice: to smooth the flesh colour field across part boundaries (L1) and
// to find the nearest hardware vertex to each flesh vertex (L5). One
// implementation, because they are the same query.
function grid(points, cell) {
  const g = new Map();
  const key = (a, b, c) => a + ',' + b + ',' + c;
  const idx = p => [Math.floor(p[0] / cell), Math.floor(p[1] / cell), Math.floor(p[2] / cell)];
  points.forEach((p, i) => {
    const [a, b, c] = idx(p.v);
    const k = key(a, b, c);
    let bin = g.get(k);
    if (!bin) g.set(k, bin = []);
    bin.push(i);
  });
  return {
    near(v, r) {
      const out = [];
      const [a, b, c] = idx(v);
      const s = Math.ceil(r / cell);
      for (let x = a - s; x <= a + s; x++)
        for (let y = b - s; y <= b + s; y++)
          for (let z = c - s; z <= c + s; z++) {
            const bin = g.get(key(x, y, z));
            if (bin) out.push(...bin);
          }
      return out;
    },
  };
}

/** Median edge length across every mesh — the sampling ruler. */
function medianEdge(meshes, diag) {
  const L = [];
  for (const m of meshes)
    for (const f of m.F || [])
      for (let k = 0; k < f.length; k++) {
        const a = m.V[f[k]], b = m.V[f[(k + 1) % f.length]];
        L.push(Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]));
      }
  if (!L.length) return diag * 0.02;
  L.sort((x, y) => x - y);
  return L[Math.floor(L.length * 0.5)] || diag * 0.02;
}

// ── the stack ──────────────────────────────────────────────────────────────
function shadeStack(spec, meshes, INFO) {
  const cfg = spec.shading || {};
  const on = k => cfg[k] !== false && cfg[k] !== 0;
  const P = k => Object.assign({}, DEFAULTS[k], (cfg[k] && typeof cfg[k] === 'object') ? cfg[k] : {});

  const live = meshes.filter(m => m.V && m.V.length);
  if (!live.length) return;

  const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
  for (const m of live) for (const v of m.V) for (let k = 0; k < 3; k++) {
    if (v[k] < lo[k]) lo[k] = v[k];
    if (v[k] > hi[k]) hi[k] = v[k];
  }
  const diag = Math.hypot(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) || 1;
  const y0 = lo[1], yr = (hi[1] - lo[1]) || 1e-6;

  const declared = declaredClasses(spec);
  for (const m of live) m._cls = classOf(m, declared.get(m.part || m.chain));
  const counts = { flesh: 0, hard: 0, fx: 0 };
  const byClass = { flesh: new Set(), hard: new Set(), fx: new Set() };
  for (const m of live) {
    counts[m._cls] += m.V.length;
    byClass[m._cls].add(m.part || m.chain || m.material || '?');
  }
  // Say WHICH pieces landed in which class. The lab could only guess at this
  // and guessed wrong on two shipped creatures; the least the engine can do,
  // having the answer for free, is print it — a trunk sitting in `hard` is a
  // one-line spec fix, and invisible unless someone says so.
  for (const k of ['flesh', 'hard', 'fx'])
    if (byClass[k].size)
      INFO.push(`shade class ${k}: ${[...byClass[k]].sort().join(', ')}`);

  // every vertex, flattened, with a back-pointer
  const pts = [];
  for (const m of live)
    m.V.forEach((v, i) => pts.push({ v, m, i, cls: m._cls }));

  // colour in OKLab, per vertex, starting from the mesh's own arc/flat colour
  for (const m of live) {
    if (!m.C) m.C = m.V.map(() => null);
    for (let i = 0; i < m.V.length; i++) {
      const c = m.C[i];
      m.C[i] = c ? lin2oklab(c) : hex2lab(m.color || '#888888');
    }
  }

  // ── L1: seam-safe flesh colour ─────────────────────────────────────────
  // A colour field that is a FUNCTION OF POSITION cannot have a seam: two
  // coincident points on either side of a junction get the same value by
  // construction. So the flesh colour is averaged spatially ACROSS parts.
  // Hardware is deliberately excluded — a bolted-on plate is supposed to have
  // a hard edge, and smoothing it would be smoothing away the design.
  //
  // The radius is tied to THIS creature's own median edge length, not to a
  // fixed fraction of its diagonal. The lab measured why: at a fixed 3% of the
  // diagonal the radius-to-edge ratio ran 1.1–1.7 across six creatures, and the
  // leftover seam ranked in exact inverse order of that ratio. A field must
  // vary slowly compared to the mesh that samples it; 1.1 edges is not slow.
  if (on('seam') !== false) {
    const sp = P('seam');
    const edge = medianEdge(live, diag);
    const R = Math.max(sp.min_frac * diag, edge * sp.radius_edges);
    const fleshPts = pts.filter(p => p.cls === 'flesh');
    if (fleshPts.length) {
      const gg = grid(fleshPts, R);
      const out = new Array(fleshPts.length);
      const r2 = R * R, sig2 = (R / 2) * (R / 2);
      fleshPts.forEach((p, n) => {
        let wsum = 0, acc = [0, 0, 0];
        for (const j of gg.near(p.v, R)) {
          const q = fleshPts[j];
          const dx = q.v[0] - p.v[0], dy = q.v[1] - p.v[1], dz = q.v[2] - p.v[2];
          const d2 = dx * dx + dy * dy + dz * dz;
          if (d2 > r2) continue;
          const w = Math.exp(-d2 / (2 * sig2));
          const c = q.m.C[q.i];
          acc[0] += c[0] * w; acc[1] += c[1] * w; acc[2] += c[2] * w;
          wsum += w;
        }
        out[n] = wsum > 0 ? [acc[0] / wsum, acc[1] / wsum, acc[2] / wsum] : p.m.C[p.i];
      });
      fleshPts.forEach((p, n) => { p.m.C[p.i] = out[n]; });
      INFO.push(`shade L1: flesh colour smoothed across parts, r=${(R / diag * 100).toFixed(1)}% of diagonal `
                + `(${(R / edge).toFixed(1)}x median edge) — seams cannot survive a position function`);
    }
  }

  // ── L2: pattern ────────────────────────────────────────────────────────
  // Flesh only, and only when the spec names a colour. The mask is the same
  // deterministic value noise the engine already uses, so it is reproducible.
  const pat = P('pattern');
  if (pat.color) {
    const PC = hex2lab(pat.color);
    const w = Math.max(0.02, 0.55 * (1 - pat.sharpness));
    const cell = Math.max(1e-6, pat.scale * diag);
    for (const p of pts) {
      if (p.cls !== 'flesh') continue;
      const n = vnoise3(p.v, cell);
      const t = pat.amount * ss(0.5 - w, 0.5 + w, n);
      if (t > 0) p.m.C[p.i] = mix(p.m.C[p.i], PC, t);
    }
    INFO.push(`shade L2: pattern ${pat.color} at ${(pat.amount * 100) | 0}% on flesh`);
  }

  // ── L3: top-to-bottom ramp, multiplied over everything ─────────────────
  const rp = P('ramp');
  const A = hex2lab(rp.bottom), MM = hex2lab(rp.mid), B = hex2lab(rp.top);
  const half = Math.max(0, rp.wm) / 2;
  const e0 = Math.min(rp.p1, Math.max(rp.p0, rp.pm - half));
  const e1 = Math.min(rp.p1, Math.max(e0, rp.pm + half));
  const lo0 = rp.p0 + (e0 - rp.p0) * rp.sh0, hi0 = e0;
  const lo1 = e1, hi1 = rp.p1 - (rp.p1 - e1) * rp.sh1;
  const bandAt = y => {
    const b0 = hi0 - lo0 < 1e-6 ? (y >= e0 ? 1 : 0) : ss(lo0, hi0, y);
    const b1 = hi1 - lo1 < 1e-6 ? (y >= e1 ? 1 : 0) : ss(lo1, hi1, y);
    let c = mix(A, MM, b0); c = mix(c, B, b1);
    return [c[0], c[1] * rp.chroma, c[2] * rp.chroma];
  };
  if (rp.amount > 0) {
    for (const p of pts) {
      if (p.cls === 'fx') continue;
      const y = (p.v[1] - y0) / yr;
      const band = bandAt(y);
      const c = p.m.C[p.i];
      // multiply, in OKLab: L multiplies, chroma follows the band's own chroma
      const t = rp.amount;
      p.m.C[p.i] = [c[0] * (1 - t) + c[0] * band[0] * t,
                    c[1] * (1 - t) + (c[1] * band[0] + band[1] * c[0]) * t,
                    c[2] * (1 - t) + (c[2] * band[0] + band[2] * c[0]) * t];
    }
    INFO.push(`shade L3: ramp ${rp.bottom} -> ${rp.mid} @${rp.pm} -> ${rp.top}, multiply ${(rp.amount * 100) | 0}%`);
  }

  // ── L4: brighten AND saturate the upper region, exactly nothing below ───
  // No blend mode can do this and it is not a tuning problem: screen and add
  // only move toward white, and white has chroma 0, so every one of them LOSES
  // chroma while gaining lightness. Observed on three creatures, every mode's
  // delta-chroma was negative. In OKLab the two quantities are independent, so
  // this just moves them:
  //     L' = L + dL*w        chroma' = chroma * (1 + (dC-1)*w)
  // Below y0 the ramp is exactly 0, so w is 0, so the vertex is returned
  // unchanged — identity, not "almost unchanged". The lab measured the maximum
  // change in the lower region across six creatures as exactly 0.
  const bo = P('boost');
  if (bo.amount > 0 && (bo.dL !== 0 || bo.dC !== 1)) {
    let clipped = 0, touched = 0;
    for (const p of pts) {
      if (p.cls === 'fx') continue;
      if (bo.target === 'flesh' && p.cls !== 'flesh') continue;
      const y = (p.v[1] - y0) / yr;
      let t = ss(bo.y0, bo.y1, y);
      if (bo.gamma !== 1) t = Math.pow(t, bo.gamma);
      if (t <= 0) continue;                         // identity, by construction
      touched++;
      const c = p.m.C[p.i];
      const w = bo.amount * t;
      const L = Math.min(1, c[0] + bo.dL * w);
      let k = 1 + (bo.dC - 1) * w;
      // Pushing chroma runs out of sRGB, and clamping per channel TURNS THE HUE
      // rather than capping the chroma. So walk back to the gamut boundary
      // instead: 12 bisections, error under 0.03%.
      if (!inGamut([L, c[1] * k, c[2] * k])) {
        clipped++;
        let a = 0, b2 = k;
        for (let it = 0; it < 12; it++) {
          const mid = (a + b2) / 2;
          if (inGamut([L, c[1] * mid, c[2] * mid])) a = mid; else b2 = mid;
        }
        k = a;
      }
      p.m.C[p.i] = [L, c[1] * k, c[2] * k];
    }
    INFO.push(`shade L4: boost dL+${bo.dL} chroma x${bo.dC} above y=${bo.y0}..${bo.y1}; `
              + `${touched} vertices touched, ${clipped} walked back to the gamut edge (0 clamped)`);
  }

  // ── L5: hardware bleeds into the flesh around it ───────────────────────
  const bl = P('bleed');
  const hardPts = pts.filter(p => p.cls === 'hard');
  if (bl.amount > 0 && hardPts.length) {
    const R = bl.radius * diag;
    const gg = grid(hardPts, R);
    let hit = 0;
    for (const p of pts) {
      if (p.cls !== 'flesh') continue;
      let best = -1, bestD = Infinity;
      for (const j of gg.near(p.v, R)) {
        const q = hardPts[j];
        const d = Math.hypot(q.v[0] - p.v[0], q.v[1] - p.v[1], q.v[2] - p.v[2]);
        if (d < bestD) { bestD = d; best = j; }
      }
      if (best < 0 || bestD >= R) continue;
      const k = Math.pow(Math.max(0, 1 - bestD / R), 1 + 8 * bl.sharpness);
      const q = hardPts[best];
      p.m.C[p.i] = mix(p.m.C[p.i], q.m.C[q.i], bl.amount * k);
      hit++;
    }
    INFO.push(`shade L5: hardware bled into ${hit} flesh vertices within ${(bl.radius * 100).toFixed(1)}% of diagonal`);
  }

  // ── L6 / L7: shading, mutually exclusive by class ──────────────────────
  // Both read the AO already baked into m.AO by ao.js. L7's fourth input in the
  // lab was a union-volume SDF that this engine does not build; what is here is
  // the horizontal light ring times AO, which is the same formula with that
  // term set to 1. Called out rather than quietly approximated.
  const hs = P('hardsh'), bs = P('bodysh');
  const ring = [];
  for (let i = 0; i < Math.max(1, bs.lights | 0); i++) {
    const az = (bs.rot + i * 360 / Math.max(1, bs.lights | 0)) * Math.PI / 180;
    const el = bs.elev * Math.PI / 180;
    ring.push([Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az)]);
  }
  let shaded = 0;
  for (const m of live) {
    if (m._cls === 'fx') continue;
    for (let i = 0; i < m.V.length; i++) {
      const ao = m.AO ? m.AO[i] : 1;
      let sh;
      if (m._cls === 'hard') {
        const a = hs.gamma === 1 ? ao : Math.pow(ao, hs.gamma);
        sh = 1 - hs.amount * (1 - a);
      } else {
        const n = m.N ? m.N[i] : [0, 1, 0];
        let sum = 0;
        for (const L of ring) sum += Math.max(0, n[0] * L[0] + n[1] * L[1] + n[2] * L[2]);
        let v = Math.max(0, Math.min(1, (sum / ring.length) * ao));
        if (bs.gamma !== 1) v = Math.pow(v, bs.gamma);
        sh = 1 - bs.amount * (1 - v);
      }
      m.C[i] = [m.C[i][0] * sh, m.C[i][1], m.C[i][2]];
      shaded++;
    }
  }
  INFO.push(`shade L6/L7: ${ring.length}-light ring x AO — hardware ${(hs.amount * 100) | 0}%, `
            + `flesh ${(bs.amount * 100) | 0}% over ${shaded} vertices`);

  // features are returned untouched, exactly as authored
  INFO.push(`shade: ${counts.flesh} flesh / ${counts.hard} hardware / ${counts.fx} feature vertices `
            + `(features take no layer and no shadow)`);

  // back to linear RGB for COLOR_0
  for (const m of live)
    for (let i = 0; i < m.C.length; i++) m.C[i] = oklab2lin(m.C[i]);
}

// deterministic value noise — same generator the compiler already uses
function vnoise3(p, scale) {
  const s = 1 / (scale || 1e-6);
  const x = p[0] * s, y = p[1] * s, z = p[2] * s;
  const xi = Math.floor(x), yi = Math.floor(y), zi = Math.floor(z);
  const xf = x - xi, yf = y - yi, zf = z - zi;
  const fade = t => t * t * (3 - 2 * t);
  const h = (a, b, c) => {
    let n = a * 374761393 + b * 668265263 + c * 1274126177;
    n = (n ^ (n >> 13)) * 1274126177;
    return ((n ^ (n >> 16)) >>> 0) / 4294967295;
  };
  const u = fade(xf), v = fade(yf), w = fade(zf);
  const lerp = (a, b, t) => a + (b - a) * t;
  return lerp(
    lerp(lerp(h(xi, yi, zi), h(xi + 1, yi, zi), u), lerp(h(xi, yi + 1, zi), h(xi + 1, yi + 1, zi), u), v),
    lerp(lerp(h(xi, yi, zi + 1), h(xi + 1, yi, zi + 1), u), lerp(h(xi, yi + 1, zi + 1), h(xi + 1, yi + 1, zi + 1), u), v),
    w);
}

module.exports = { shadeStack, DEFAULTS, lin2oklab, oklab2lin, inGamut, hex2lab };