Skip to content

Playbook and Three.js code kit for detailed dioramas: classic pixel art, stroked toon or pixel + stroke; two intake gates for look and model sourcing; free orbit, palette snap and ink; animated toy-scale cast; per-entity frame QA.

12.9 KB
Raw Blame
import * as THREE from 'three';
import { roundedBoxGeometry } from '../core/geometry.js';

/**
 * Diorama proportions: a 1.69 m figure with a tapered lathe torso and
 * pelvis, chunky limbs, and joint fillers so a bend never opens a gap.
 * The figure faces +Z. Positive hip/shoulder X rotation swings a limb
 * backwards; negative swings it forwards.
 */
export const RIG = {
  hipY: 0.86,
  hipX: 0.10,
  thigh: 0.42,
  shin: 0.40,
  shoulderY: 0.415,
  shoulderX: 0.182,
  upperArm: 0.30,
  foreArm: 0.27,
  headY: 0.584,
};

function part(parent, geo, mat, x, y, z, opts = {}) {
  const m = new THREE.Mesh(geo, mat);
  m.position.set(x, y, z);
  if (opts.rotation) m.rotation.set(...opts.rotation);
  if (opts.scale) m.scale.set(...opts.scale);
  m.castShadow = true;
  m.receiveShadow = true;
  parent.add(m);
  return m;
}

function capsule(parent, r, len, mat, x, y, z, opts = {}) {
  const geo = new THREE.CapsuleGeometry(r, Math.max(0.01, len), 8, 18);
  return part(parent, geo, mat, x, y, z, opts);
}

function sphere(parent, r, mat, x, y, z, scale = [1, 1, 1], opts = {}) {
  return part(parent, new THREE.SphereGeometry(r, 24, 18), mat, x, y, z, { ...opts, scale });
}

function box(parent, w, h, d, r, mat, x, y, z, opts = {}) {
  const geo = roundedBoxGeometry(w, h, d, Math.min(r, Math.min(w, h, d) * 0.48), 3);
  return part(parent, geo, mat, x, y, z, opts);
}

/** Lathe a side profile, then flatten it front-to-back. */
function lathe(parent, profile, flatten, mat, y, x = 0, z = 0) {
  const pts = profile.map(([r, h]) => new THREE.Vector2(r, h));
  const geo = new THREE.LatheGeometry(pts, 26);
  geo.scale(1, 1, flatten);
  const m = new THREE.Mesh(geo, mat);
  m.position.set(x, y, z);
  m.castShadow = true;
  m.receiveShadow = true;
  parent.add(m);
  return m;
}

const TORSO = [
  [0.135, -0.02],
  [0.165, 0.09],
  [0.190, 0.22],
  [0.198, 0.33],
  [0.196, 0.40],
  [0.168, 0.47],
  [0.090, 0.53],
  [0.062, 0.56],
];

const PELVIS = [
  [0.105, -0.24],
  [0.150, -0.17],
  [0.176, -0.07],
  [0.180, 0.04],
  [0.168, 0.12],
];

const SHORTS = [
  [0.150, -0.30],
  [0.182, -0.20],
  [0.190, -0.08],
  [0.188, 0.06],
  [0.178, 0.12],
];

const BRIEFS = [
  [0.100, -0.23],
  [0.152, -0.18],
  [0.184, -0.06],
  [0.183, 0.07],
  [0.172, 0.12],
];

export function buildPerson(mats, opts = {}) {
  const skin = opts.skin ?? mats.skinTones[0];
  const hairMat = opts.hair ?? mats.hair[0];
  const suit = opts.suit ?? mats.suits.coral;
  const suitStyle = opts.suitStyle ?? 'onepiece';
  // A darker clone of the skin for creases, lids and seams.
  const shade = skin.clone();
  shade.color = skin.color.clone().multiplyScalar(0.86);
  const root = new THREE.Group();
  const J = {};

  const pelvis = new THREE.Group();
  pelvis.position.y = RIG.hipY;
  root.add(pelvis);
  J.pelvis = pelvis;

  // Hips, always skin; swimwear is layered over them.
  lathe(pelvis, PELVIS, 0.86, suitStyle === 'trunks' || suitStyle === 'briefs' ? suit : skin, 0);

  const torso = new THREE.Group();
  torso.position.y = 0.02;
  pelvis.add(torso);
  J.torso = torso;

  const torsoMat = suitStyle === 'trunks' ? skin : suit;
  lathe(torso, TORSO, 0.72, torsoMat, 0);

  if (suitStyle === 'onepiece' || suitStyle === 'briefs') {
    if (opts.suitAccent) {
      const band = new THREE.Mesh(
        new THREE.CylinderGeometry(0.201, 0.200, 0.06, 22),
        opts.suitAccent
      );
      band.position.set(0, 0.315, 0);
      band.scale.z = 0.735;
      band.castShadow = true;
      torso.add(band);
    }
    lathe(pelvis, BRIEFS, 0.88, suit, 0);

  } else if (suitStyle === 'trunks') {
    lathe(pelvis, SHORTS, 0.88, suit, 0);
    const band = new THREE.Mesh(
      new THREE.CylinderGeometry(0.187, 0.19, 0.045, 22),
      opts.suitAccent ?? suit
    );
    band.position.set(0, 0.015, 0);
    band.scale.z = 0.885;
    band.castShadow = true;
    pelvis.add(band);
    for (const s of [-1, 1]) {
      box(pelvis, 0.024, 0.20, 0.05, 0.01, opts.suitAccent ?? suit, s * 0.185, -0.12, 0.02);
    }
    box(pelvis, 0.07, 0.028, 0.02, 0.008, opts.suitAccent ?? suit, 0, 0.05, 0.155);
  }

  // Collarbones and chest planes on bare torsos.
  if (suitStyle === 'trunks' || suitStyle === 'briefs') {
    for (const s of [-1, 1]) {
      capsule(torso, 0.011, 0.10, shade, s * 0.095, 0.455, 0.098, {
        rotation: [0, 0, s * 1.32],
        castShadow: false,
      });
      sphere(torso, 0.062, skin, s * 0.078, 0.352, 0.10, [0.95, 0.72, 0.42]);
    }
    box(torso, 0.012, 0.012, 0.006, 0.005, shade, 0, 0.075, 0.148, { castShadow: false });
  }
  if (opts.suitAccent && (suitStyle === 'onepiece' || suitStyle === 'briefs')) {
    box(torso, 0.034, 0.030, 0.008, 0.008, opts.suitAccent, -0.085, 0.355, 0.132, {
      castShadow: false,
    });
  }

  // Neck and head.
  capsule(torso, 0.057, 0.075, skin, 0, 0.545, 0);
  const head = new THREE.Group();
  head.position.y = RIG.headY;
  torso.add(head);
  J.head = head;

  sphere(head, 0.115, skin, 0, 0.105, 0.004, [1.0, 1.1, 0.96]);
  sphere(head, 0.089, skin, 0, 0.028, 0.018, [0.94, 0.78, 0.92]);

  // Ears and a soft nose wedge keep the head from reading as a ball.
  for (const s of [-1, 1]) {
    sphere(head, 0.028, skin, s * 0.112, 0.10, 0.0, [0.55, 1.0, 0.85]);
  }
  box(head, 0.038, 0.054, 0.044, 0.018, skin, 0, 0.090, 0.106, {
    rotation: [-0.12, 0, 0],
  });

  if (!opts.goggles) {
    for (const s of [-1, 1]) {
      sphere(head, 0.017, mats.eye, s * 0.044, 0.115, 0.104, [1.0, 1.15, 0.5], {
        castShadow: false,
      });
      box(head, 0.05, 0.011, 0.012, 0.004, hairMat, s * 0.047, 0.146, 0.102, {
        rotation: [0, 0, s * 0.12],
      });
    }
    box(head, 0.052, 0.013, 0.012, 0.005, mats.mouth, 0, 0.045, 0.106);
    // Fine face detail: lids, cheek planes, chin, nostrils, lower lip.
    for (const s of [-1, 1]) {
      box(head, 0.046, 0.007, 0.010, 0.003, shade, s * 0.044, 0.101, 0.104, {
        rotation: [0, 0, s * 0.10],
        castShadow: false,
      });
      sphere(head, 0.030, skin, s * 0.060, 0.078, 0.078, [0.95, 0.62, 0.55]);
    }
    box(head, 0.046, 0.026, 0.036, 0.012, skin, 0, 0.026, 0.094);
    box(head, 0.038, 0.009, 0.012, 0.004, shade, 0, 0.034, 0.106, { castShadow: false });
    for (const s of [-1, 1]) {
      box(head, 0.008, 0.007, 0.008, 0.003, shade, s * 0.013, 0.060, 0.132, { castShadow: false });
    }
  }

  // Swim cap sits over a bald head.
  if (opts.cap) {
    const capMesh = new THREE.Mesh(
      new THREE.SphereGeometry(0.121, 24, 16, 0, Math.PI * 2, 0, 1.62),
      opts.cap
    );
    capMesh.position.set(0, 0.105, 0);
    capMesh.scale.set(1.02, 1.06, 1.0);
    capMesh.castShadow = true;
    head.add(capMesh);
  }

  // Hair: a rounded cap over the skull, with optional length at the back.
  if (opts.hairStyle !== 'bald' && !opts.cap) {
    const style = opts.hairStyle ?? 'short';
    const capMat = opts.cap ?? hairMat;
    const theta = style === 'buzz' ? 1.35 : 1.85;
    const cap = new THREE.Mesh(
      new THREE.SphereGeometry(0.121, 24, 16, 0, Math.PI * 2, 0, theta),
      capMat
    );
    cap.position.set(0, 0.105, 0);
    cap.scale.set(1.02, 1.06, 1.0);
    cap.castShadow = true;
    head.add(cap);
    // Fringe across the forehead.
    box(head, 0.20, 0.055, 0.05, 0.02, capMat, 0, 0.175, 0.093, {
      rotation: [0.18, 0, 0],
    });

    if (style === 'long' || style === 'bun') {
      sphere(head, 0.10, capMat, 0, 0.075, -0.055, [1.0, 1.15, 0.7]);
      for (const s of [-1, 1]) {
        sphere(head, 0.05, capMat, s * 0.098, 0.055, -0.02, [0.8, 1.5, 0.9]);
      }
    }
    if (style === 'bun') {
      sphere(head, 0.07, capMat, 0, 0.165, -0.10, [1, 0.95, 0.9]);
    }
  }

  if (opts.sunglasses) {
    box(head, 0.175, 0.05, 0.024, 0.011, mats.goggle, 0, 0.118, 0.098);
  }
  if (opts.goggles) {
    for (const s of [-1, 1]) {
      box(head, 0.072, 0.048, 0.026, 0.012, mats.goggle, s * 0.05, 0.118, 0.10);
    }
    box(head, 0.045, 0.02, 0.024, 0.008, mats.goggleStrap, 0, 0.118, 0.104);
    box(head, 0.235, 0.03, 0.235, 0.012, mats.goggleStrap, 0, 0.135, -0.004);
  }

  if (opts.hat) {
    const hat = new THREE.Group();
    hat.position.y = 0.192;
    hat.rotation.x = -0.05;
    const brim = new THREE.Mesh(new THREE.CylinderGeometry(0.20, 0.212, 0.018, 24), opts.hat);
    brim.castShadow = true;
    hat.add(brim);
    const crown = new THREE.Mesh(new THREE.CylinderGeometry(0.100, 0.120, 0.115, 20), opts.hat);
    crown.position.y = 0.062;
    crown.castShadow = true;
    hat.add(crown);
    const band = new THREE.Mesh(
      new THREE.CylinderGeometry(0.112, 0.12, 0.026, 20),
      opts.hatBand ?? mats.suits.navy
    );
    band.position.y = 0.016;
    hat.add(band);
    head.add(hat);
  }

  // Arms: joint spheres sit just inside the limb radius so bends stay sealed.
  for (const s of [-1, 1]) {
    const shoulder = new THREE.Group();
    shoulder.position.set(s * RIG.shoulderX, RIG.shoulderY, 0);
    torso.add(shoulder);
    sphere(shoulder, 0.062, skin, 0, 0, 0, [1, 0.94, 1]);
    capsule(shoulder, 0.057, 0.166, skin, 0, -RIG.upperArm / 2, 0);

    const elbow = new THREE.Group();
    elbow.position.y = -RIG.upperArm;
    shoulder.add(elbow);
    sphere(elbow, 0.049, skin, 0, 0, 0);
    capsule(elbow, 0.05, 0.15, skin, 0, -RIG.foreArm / 2, 0);

    const wrist = new THREE.Group();
    wrist.position.y = -RIG.foreArm + 0.01;
    elbow.add(wrist);
    box(wrist, 0.072, 0.098, 0.058, 0.024, skin, 0, -0.045, 0.004);
    box(wrist, 0.026, 0.058, 0.03, 0.012, skin, s * 0.042, -0.032, 0.014, {
      rotation: [0, 0, -s * 0.55],
    });

    // Knuckle grooves and an optional band/watch at the wrist.
    for (let f = 0; f < 3; f++) {
      box(wrist, 0.006, 0.052, 0.012, 0.002, shade, -0.022 + f * 0.022, -0.062, 0.030, {
        castShadow: false,
      });
    }
    if (opts.band) {
      const strap = new THREE.Mesh(new THREE.CylinderGeometry(0.060, 0.060, 0.024, 16), opts.band);
      strap.position.set(0, 0.008, 0.0);
      strap.castShadow = true;
      wrist.add(strap);
    }

    if (suitStyle === 'onepiece' && opts.suitSleeve) {
      capsule(shoulder, 0.066, 0.09, suit, 0, -0.065, 0);
    }

    J[s < 0 ? 'shoulderL' : 'shoulderR'] = shoulder;
    J[s < 0 ? 'elbowL' : 'elbowR'] = elbow;
    J[s < 0 ? 'wristL' : 'wristR'] = wrist;
  }

  // Legs.
  for (const s of [-1, 1]) {
    const hip = new THREE.Group();
    hip.position.set(s * RIG.hipX, -0.04, 0);
    pelvis.add(hip);
    sphere(hip, 0.078, suitStyle === 'trunks' || suitStyle === 'briefs' ? suit : skin, 0, 0, 0);
    capsule(hip, 0.086, 0.224, skin, 0, -RIG.thigh / 2, 0);

    const knee = new THREE.Group();
    knee.position.y = -RIG.thigh;
    hip.add(knee);
    sphere(knee, 0.069, skin, 0, 0, 0);
    capsule(knee, 0.068, 0.244, skin, 0, -RIG.shin / 2, 0);

    const ankle = new THREE.Group();
    ankle.position.y = -RIG.shin;
    knee.add(ankle);
    box(ankle, 0.105, 0.07, 0.215, 0.03, opts.shoe ?? skin, 0, 0.017, 0.045);
    box(ankle, 0.098, 0.04, 0.055, 0.016, opts.shoe ?? skin, 0, 0.006, 0.158);

    sphere(knee, 0.048, skin, 0, -0.012, 0.040, [1.0, 1.05, 0.62]);
    for (let f = 0; f < 2; f++) {
      box(ankle, 0.007, 0.036, 0.05, 0.003, shade, -0.014 + f * 0.026, 0.010, 0.168, {
        castShadow: false,
      });
    }
    box(ankle, 0.030, 0.018, 0.026, 0.008, shade, -0.030, 0.020, 0.196, { castShadow: false });

    J[s < 0 ? 'hipL' : 'hipR'] = hip;
    J[s < 0 ? 'kneeL' : 'kneeR'] = knee;
    J[s < 0 ? 'ankleL' : 'ankleR'] = ankle;
  }

  return { group: root, joints: J, opts };
}

export function setPose(p, pose = {}) {
  const J = p.joints;
  const r = (obj, v) => {
    if (!obj) return;
    obj.rotation.set(v?.[0] ?? 0, v?.[1] ?? 0, v?.[2] ?? 0);
  };
  r(J.torso, pose.torso);
  r(J.head, pose.head);
  r(J.shoulderL, pose.shoulderL);
  r(J.shoulderR, pose.shoulderR);
  r(J.elbowL, pose.elbowL);
  r(J.elbowR, pose.elbowR);
  r(J.wristL, pose.wristL);
  r(J.wristR, pose.wristR);
  r(J.hipL, pose.hipL);
  r(J.hipR, pose.hipR);
  r(J.kneeL, pose.kneeL);
  r(J.kneeR, pose.kneeR);
  r(J.ankleL, pose.ankleL);
  r(J.ankleR, pose.ankleR);
  if (pose.pelvis) r(J.pelvis, pose.pelvis);
}

export function easePose(p, pose, k) {
  const J = p.joints;
  const apply = (obj, v) => {
    if (!obj) return;
    const tx = v?.[0] ?? 0;
    const ty = v?.[1] ?? 0;
    const tz = v?.[2] ?? 0;
    obj.rotation.x += (tx - obj.rotation.x) * k;
    obj.rotation.y += (ty - obj.rotation.y) * k;
    obj.rotation.z += (tz - obj.rotation.z) * k;
  };
  apply(J.torso, pose.torso);
  apply(J.head, pose.head);
  apply(J.shoulderL, pose.shoulderL);
  apply(J.shoulderR, pose.shoulderR);
  apply(J.elbowL, pose.elbowL);
  apply(J.elbowR, pose.elbowR);
  apply(J.wristL, pose.wristL);
  apply(J.wristR, pose.wristR);
  apply(J.hipL, pose.hipL);
  apply(J.hipR, pose.hipR);
  apply(J.kneeL, pose.kneeL);
  apply(J.kneeR, pose.kneeR);
  apply(J.ankleL, pose.ankleL);
  apply(J.ankleR, pose.ankleR);
  if (pose.pelvis) apply(J.pelvis, pose.pelvis);
}

export function blendPose(base, add) {
  const out = {};
  for (const k of new Set([...Object.keys(base), ...Object.keys(add)])) {
    const a = base[k] ?? [0, 0, 0];
    const b = add[k] ?? [0, 0, 0];
    out[k] = [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
  }
  return out;
}