@pieai/swimmer-avatar-kit 0.1.0

package/vendor/kindergrimm/src/gloss/gparts/specs.js

@@ -0,0 +1,124 @@
+// SPECTACLES — the first of the EXTRAS, and the ones that change a face
+// most for the least geometry: two frames, a bridge, and the character is
+// suddenly somebody in particular.
+//
+// Every style is stacked plates, the same trick as a pupil on a white:
+// a FRAME (a ring outline, so it is a frame rather than a disc) and,
+// where the style wants one, a LENS filled behind it. The catalogue is
+// really two questions — round or square, and see-through or not.
+//
+// WHERE THEY SIT is the whole difficulty, and it is not a constant. An
+// `orb` eye is a ball standing three quarters of its own radius off the
+// head; a plate eye is almost flush. So the eyes publish `eyeProud` and
+// the layout hands it over — spectacles placed for a flat eye cut
+// straight through an eyeball, which is exactly what happened.
+const STYLE = {
+  none:    null,
+  // wire rounds. Thin, dark, the reading-glasses read
+  round:   { outline: 'ring', wf: 1.28, hf: 1.28, thick: .16 },
+  // heavy squares — the ones you actually notice at sheet scale
+  square:  { outline: 'rring', wf: 1.34, hf: 1.14, thick: .22, r: .34 },
+  // filled lenses in ink: shades. No frame of its own, because a dark
+  // lens IS its own silhouette and a frame round it just goes muddy
+  sunnies: { outline: 'rring', wf: 1.42, hf: 1.02, thick: .16, r: .3, lens: 'ink' },
+  // a pale lens behind a dark frame: the goggle read, and the one
+  // style where the eye still shows THROUGH something
+  goggles: { outline: 'ring', wf: 1.5, hf: 1.5, thick: .26, lens: 'lite' },
+  // ONE lens, on one side, and the asymmetry is the joke
+  monocle: { outline: 'ring', wf: 1.3, hf: 1.3, thick: .18, single: true },
+};
+
+export const SPECS_STYLES = Object.keys(STYLE);
+
+export const Specs = {
+  // AFTER the eyes and the brows: it reads their sizes off the layout,
+  // and it has to sit in front of whatever they built.
+  id: 'specs', label: 'specs', order: 4,
+
+  // Anecdotal, like the brows and for the same reason: glasses on every
+  // character stop being a character and become the house style.
+  gen: (rng, C) => ({
+    style: C.pick(rng, 'style', [['none', 88], ['round', 4], ['square', 3],
+                                 ['sunnies', 2], ['goggles', 2], ['monocle', 1]]),
+    size: C.range(rng, 'size', .92, 1.18),     // × the eye's own size
+    ink: C.chance(rng, 'ink', .72),            // frame in ink, or in the warm
+    side: rng.chance(.5) ? 1 : -1,             // which eye a monocle takes
+  }),
+
+  meta: () => ({
+    style: { label: 'style', pick: SPECS_STYLES },
+    size: { label: 'size', range: [.6, 1.6] },
+    ink: { label: 'dark frame', bool: true },
+  }),
+
+  build(add, P, L) {
+    const S = P.specs;
+    const st = STYLE[S.style];
+    if (!st) return;
+    const r = L.eyeSize * S.size;
+    // ink, or the accessory colour — never the character's own warm, which
+    // on a humanoid is another skin tone and vanishes
+    const frame = S.ink ? L.ink : L.acc;
+    // clear of whatever the eyes built, plus air. `eyeProud` is in eye
+    // units, so it scales with them.
+    const lift = L.eyeSize * (L.eyeProud + .16);
+    // spectacles are plastic, not whatever the character is poured in
+    const fin = 'glossy';
+    const w = r * st.wf, h = r * st.hf;
+    const d = r * .18;
+
+    for (const [id, side] of [['specL', -1], ['specR', 1]]) {
+      if (st.single && side !== S.side) continue;
+      // `onFace`, not `at`: a lens is wider than the eye under it, so
+      // it is the one that walks at the silhouette
+      const a = L.onFace(side * L.eyeX, L.eyeY, { halfW: w });
+
+      if (st.lens) {
+        // behind the frame, and a hair smaller, so the frame's inner
+        // edge always overlaps it and no seam of skin shows between
+        add({ type: 'plate', id: id + 'Lens', outline: st.outline === 'ring' ? 'ellipse' : 'rect',
+              w: w * .94, h: h * .94, r: st.r == null ? undefined : Math.min(w, h) * st.r,
+              p: a.p, n: a.n, d: d * .5, bevel: d * .2,
+              proud: lift - d * .3,
+              color: st.lens === 'ink' ? L.ink : L.lite , finish: fin });
+      }
+      add({ type: 'plate', id, outline: st.outline,
+            w, h, thick: st.thick,
+            r: st.r == null ? undefined : Math.min(w, h) * st.r,
+            p: a.p, n: a.n, d, bevel: Math.min(d * .5, Math.min(w, h) * st.thick * .6),
+            proud: lift, color: frame , finish: fin });
+    }
+
+    // THE BRIDGE — a short bar between the two, on the midline. A pair
+    // of lenses with nothing joining them reads as two stickers.
+    if (!st.single) {
+      const b = L.at(0, L.eyeY);
+      // the lens centre's WORLD x, from the same call that placed the
+      // frames — `eyeX` is a face coordinate and `w` a world length,
+      // and multiplying them gave a bar that reached neither lens
+      const xw = Math.abs(L.onFace(L.eyeX, L.eyeY, { halfW: w }).p[0]);
+      // run out past each frame's inner edge, most of the way through
+      // its rim: the bevel eats a hair off the band's ends, and a bar
+      // that only kisses the rim's midline can still fall short of it
+      const span = xw - w * (1 - st.thick * .75);
+      if (span > 0)
+        add({ type: 'plate', id: 'specBridge', outline: 'band', curve: 'line',
+              w: span, h: r * .09, tube: r * .09,
+              p: b.p, n: b.n, d: d * .8, bevel: d * .3,
+              proud: lift - d * .1, color: frame , finish: fin });
+    }
+
+    // and a STRAP for the goggles: one band round the head, which is
+    // the only thing that says these are worn rather than held
+    if (st.strap) {
+      for (const side of [-1, 1]) {
+        const a = L.onFace(side * (L.eyeX + .62), L.eyeY, { facing: .12 });
+        add({ type: 'plate', id: 'specStrap' + (side < 0 ? 'L' : 'R'),
+              outline: 'band', curve: 'line',
+              w: r * .5, h: r * .16, tube: r * .16,
+              p: a.p, n: a.n, d: d * .7, bevel: d * .25,
+              proud: r * .1, color: frame , finish: fin });
+      }
+    }
+  },
+};

package/vendor/kindergrimm/src/gloss/grig.d.ts

@@ -0,0 +1,41 @@
+import type { Group, Material, Mesh, Texture } from "three";
+
+export interface GRecipe {
+  seed: number;
+  species: string | null;
+  body: string | null;
+  stance: string | null;
+  palette: string | null;
+  colorIx: number | null;
+  material: string | null;
+  parts: Record<string, { params?: unknown | null; rr?: number }>;
+}
+
+export type MaterialFor = (
+  finish: string,
+  color: string,
+  shell?: boolean,
+  print?: { key: string; tex: Texture } | null,
+) => Material;
+
+export interface GlossBuilt {
+  group: Group;
+  head: Group;
+  face: Record<string, Mesh>;
+  P: Record<string, unknown>;
+  L: { s: number; H: number; W: number; cy: number };
+  bounds: { w: number; h: number; cy: number; minY: number; maxY: number };
+  stats: { buildMs: number; verts: number; meshes: number };
+}
+
+export const GPARTS: readonly { id: string; label: string }[];
+export const GPART_BY_ID: Record<string, { id: string; label: string }>;
+export const BODY_IDS: readonly string[];
+export const BODY_WEIGHTS: readonly [string, number][];
+export const STANCE_IDS: readonly string[];
+export const STANCE_WEIGHTS: readonly [string, number][];
+
+export function newGRecipe(seed?: number): GRecipe;
+export function ensureGParams(recipe: GRecipe): GRecipe;
+export function rerollGPart(recipe: GRecipe, id: string): void;
+export function buildGloss(recipe: GRecipe, options: { materialFor: MaterialFor }): GlossBuilt;

package/vendor/kindergrimm/src/gloss/grig.js

@@ -0,0 +1,286 @@
+// ---------------------------------------------------------------
+// THE RIG — recipe in, character out, and the recipe is the ONLY state, so
+// the same JSON gives the same character on any machine.
+//
+//   recipe = {
+//     seed,                       // one integer; the whole character
+//     body,                       // which shape (one for now: sphere)
+//     palette, colorIx,           // which five colours, and which of them
+//     material,                   // one of `MATERIAL_IDS`
+//     parts: { [id]: { params, rr? } }
+//   }
+//
+// Every part gen()s its params, the layout measures once, each part
+// pushes SPECS, and this file stamps them. A part never touches
+// three.js and never builds a material — it names a colour from the
+// layout and a shape from the catalogue.
+//
+// The face comes back as a map of meshes (`eyeL`, `mouth`, …) and that
+// map is the animation surface: a blink is `eyeL.scale.y`, a glance is
+// a nudge in x, and neither costs a rebuild. That is the whole reason
+// the features are separate objects instead of one welded model.
+// ---------------------------------------------------------------
+import * as THREE from 'three';
+import { makeRng, hashStr } from '../rng.js';
+import { plateGeometry, solidGeometry, skullGeometry, basisAt } from './gshape.js';
+import { buildGlossLayout } from './glayout.js';
+import { GPARTS, GPART_BY_ID } from './gparts/index.js';
+import { PALETTES, PALETTE_BY_ID, PALETTE_DEAL_IDS, INK, SCLERA, MAW, tint, luma } from './gpalette.js';
+import { MATERIAL_WEIGHTS } from './gmedia.js';
+import { gcastingFor, pickGBody, pickGStance, GSPECIES, GSPECIES_WEIGHTS } from './gspecies.js';
+import { isMeshForm } from './gform.js';
+import { clothPrint } from './gtexture.js';
+
+export { GPARTS, GPART_BY_ID };
+
+export const BODY_IDS = ['sphere', 'cube', 'rock', 'slime'];
+
+// How an un-opinionated species is poured. WEIGHTED, not uniform: the
+// ball and the block carry the sheet, and the two bent forms are the
+// treats — dealt evenly they were 40% of a sheet, and a rock is a
+// strong enough silhouette that four of them in a row stop being a
+// surprise. A humanoid is neither shape, and says so in its profile.
+// The lump shapes lost a little of the wildcard's share when they
+// became SPECIES of their own — a dedicated rock deal plus the old
+// wildcard rate made half the sheet geology.
+export const BODY_WEIGHTS = [['sphere', 38], ['cube', 36], ['rock', 16], ['slime', 10]];
+
+export const STANCE_IDS = ['none', 'biped'];
+
+// Head-only carries the sheet — it is the house look, and a body is
+// the treat, the same bargain as the bent forms above. Frequency is
+// art direction here like everywhere else.
+export const STANCE_WEIGHTS = [['none', 69], ['biped', 31]];
+
+export function newGRecipe(seed = (Math.random() * 1e9) | 0) {
+  return { seed, species: null, body: null, stance: null, palette: null, colorIx: null,
+           material: null, parts: {} };
+}
+
+// a WEIGHTED pick, because "how often" is most of the art direction
+// here: brows are anecdotal, noses are a quarter of the sheet, chrome
+// is once a sheet, and a uniform pick over a table cannot say any of
+// it. It lives out here rather than on `partRng` because the CAST rng
+// needs it too — a finish is dealt by frequency the same as a style.
+// Costs exactly one draw, so it can replace a `pick` without shifting
+// anything downstream of it in the stream.
+const wpick = (rng, pairs) => {
+  let total = 0; for (const p of pairs) total += p[1];
+  let x = rng.r(0, total);
+  for (const p of pairs) if ((x -= p[1]) < 0) return p[0];
+  return pairs[pairs.length - 1][0];
+};
+
+const partRng = (recipe, id) => {
+  const rng = makeRng(hashStr(`${recipe.seed}:g:${id}:${recipe.parts[id]?.rr || 0}`));
+  rng.wpick = pairs => wpick(rng, pairs);
+  return rng;
+};
+
+/** fills in anything the recipe has not already been TOLD. Every field
+ *  uses ??=, which is what lets the crowd's filters pin one dimension
+ *  and let the rest roll. */
+export function ensureGParams(recipe) {
+  const rng = makeRng(hashStr(`${recipe.seed}:gcast`));
+  // the species FIRST: it loads the dice for everything after it —
+  // the body form it prefers, and every part's own rolls
+  recipe.species ??= wpick(rng, GSPECIES_WEIGHTS);
+  // a stance PINNED before the deal (the crowd's filter) narrows the
+  // body: the modeled forms cannot stand on a frame — see below
+  const wantFrame = !!recipe.stance && recipe.stance !== 'none';
+  recipe.body ??= pickGBody(recipe.species, rng, BODY_WEIGHTS,
+                            wantFrame ? { without: isMeshForm } : {});
+  // A species may NAME a palette and a material, and exactly one does.
+  // The standing rule is that it must not — what a character is made of is a
+  // separate lever, and a lavender panda is still a panda. The
+  // humanoid is the exception the rule was waiting for: it is made of
+  // SKIN, and a chrome one is not a humanoid in another finish, it is
+  // a different object. Everyone else still leaves both alone, and a
+  // pinned filter still wins over either (the ??= runs first).
+  const SP = GSPECIES[recipe.species];
+  recipe.palette ??= SP?.palette ?? rng.pick(PALETTE_DEAL_IDS);
+  recipe.material ??= SP?.material ?? wpick(rng, MATERIAL_WEIGHTS);
+  recipe.colorIx ??= rng.ri(0, PALETTE_BY_ID[recipe.palette].colors.length - 1);
+  // dealt LAST in the cast stream, so existing seeds keep the species,
+  // body and colours they already had. A modeled form never takes a
+  // frame — a rock's foot and a slime's base are already its bottom —
+  // but a PINNED stance (the crowd's filter) still wins, because the
+  // ??= runs first.
+  recipe.stance ??= isMeshForm(recipe.body) ? 'none'
+    : pickGStance(recipe.species, rng, STANCE_WEIGHTS);
+
+  const C = gcastingFor(recipe.species);
+  for (const part of GPARTS) {
+    recipe.parts[part.id] ??= {};
+    recipe.parts[part.id].params ??= part.gen(partRng(recipe, part.id), C(part.id));
+  }
+  return recipe;
+}
+
+export function rerollGPart(recipe, id) {
+  const slot = recipe.parts[id];
+  if (!slot) return;
+  slot.rr = (slot.rr || 0) + 1;
+  slot.params = null;
+  ensureGParams(recipe);
+}
+
+/** the four colours every part draws from, all off the one palette. */
+function colorsFor(recipe) {
+  const pal = PALETTE_BY_ID[recipe.palette] ?? PALETTES[0];
+  const body = pal.colors[recipe.colorIx % pal.colors.length];
+
+  // The warm bits (cheeks) take ANOTHER colour from the same five, and
+  // it has to be the WARMEST one — not, as it was, the one furthest in
+  // lightness. Furthest-in-lightness picked the blue out of a pale
+  // palette often enough that cheeks came out cold, which does not read
+  // as a blush at all: it reads as tears. Score by how far toward red
+  // a colour sits, and break ties on contrast against the body so it
+  // still shows up.
+  const warmth = hex => {
+    const n = parseInt(hex.slice(1), 16);
+    return ((n >> 16 & 255) - (n & 255)) / 255;
+  };
+  let warm = body, best = -Infinity;
+  for (const c of pal.colors) {
+    if (c === body) continue;
+    const score = warmth(c) * 2 + Math.abs(luma(c) - luma(body)) * .5;
+    if (score > best) { best = score; warm = c; }
+  }
+  return { body, warm, ink: INK, sclera: SCLERA, maw: MAW, lite: tint(body, .55) };
+}
+
+/**
+ * recipe → { group, face, P, L, stats }.
+ * `face` maps a feature id to its mesh.
+ */
+export function buildGloss(recipe, { materialFor } = {}) {
+  ensureGParams(recipe);
+  const P = Object.fromEntries(GPARTS.map(p => [p.id, recipe.parts[p.id].params]));
+  const L = buildGlossLayout(P, colorsFor(recipe), recipe.body, recipe.stance ?? 'none');
+  const finish = recipe.material;
+
+  const t0 = performance.now();
+  const specs = [];
+  const add = s => specs.push(s);
+  for (const part of GPARTS) part.build(add, P, L);
+
+  const group = new THREE.Group();
+  // THE HEAD IS ITS OWN GROUP, pivoted at its centre. The gaze spring
+  // turns the head, and on a character with a torso the torso must not turn
+  // with it — so the pages write yaw/pitch to `head`, not `group`. On
+  // a head-only character that is the whole character, same as it always was, just
+  // pivoting about its middle instead of about the floor.
+  const head = new THREE.Group();
+  head.position.y = L.cy;
+  head.userData.restY = L.cy;
+  group.add(head);
+  const face = {};
+  let verts = 0;
+
+  for (const spec of specs) {
+    // the exponent travels as `exp`, NEVER `n`: a placed solid also
+    // carries its surface normal as `n`, and the two silently collide
+    // in the spec literal — an array reaches Math.pow and every vertex
+    // goes NaN. It happened; the key is different so it cannot again.
+    // `mesh` is arrays built elsewhere and stamped here — the skull
+    // (gskull.js) and the hair (ghair.js). `skull` is the old name for
+    // it and still works.
+    const geo = spec.type === 'mesh' || spec.type === 'skull'
+      ? skullGeometry(spec.mesh ?? spec.skull)
+      : spec.type === 'solid'
+      ? solidGeometry(spec.rx, spec.ry, spec.rz, spec.exp ?? 2, spec.dome, spec.domeFrom)
+      : plateGeometry(spec);
+    // The SHELL is the body — head, torso and limbs, the character's own
+    // pour. Everything else is a feature set into it, and takes
+    // whatever `gmedia.js` says a feature may wear — nobody knits an
+    // eye, and a plate's UVs could not carry a stitch even if somebody
+    // did. A knitted bear's belly, though, is knitted.
+    const shell = spec.id === 'body' || !!spec.shell;
+    // A spec may NAME its finish. Hair does (a wool humanoid is a
+    // knitted head, not a knitted haircut) and so does the frame's
+    // outfit — cloth, gloves, shoes are `acc`, never the pour. A spec
+    // may also carry a PRINT: the torso's screen-printed graphic, baked
+    // once per (motif, cloth, ink) in `gtexture.js`.
+    const print = spec.print
+      ? clothPrint(spec.print.motif, spec.print.cloth, spec.print.ink) : null;
+    const mat = materialFor(spec.finish ?? finish, spec.color, shell, print);
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.name = spec.id;
+
+    if (spec.pos) {
+      mesh.position.set(spec.pos[0], spec.pos[1], spec.pos[2]);
+      // an arm hanging a little out from the shoulder — the one
+      // rotation a placed solid may carry
+      if (spec.tilt) mesh.rotation.z = spec.tilt;
+    } else {
+      const b = basisAt(spec.p, spec.n, spec.proud ?? 0, spec.roll ?? 0);
+      mesh.position.copy(b.position);
+      mesh.quaternion.copy(b.quaternion);
+      // an offset is in the FEATURE's own plane, not the world's — so a
+      // catchlight stays up-and-left of its eye however the eye is
+      // tilted or wherever on the head it landed
+      if (spec.offset) { mesh.translateX(spec.offset[0]); mesh.translateY(spec.offset[1]); }
+    }
+
+    // Only the body casts, and whatever ASKS to. A face feature lies
+    // flush against a body that is already casting, and the key's blur
+    // would smear its shadow back across the very face it sits on —
+    // but hair is a real volume standing off the head, and hair that
+    // casts nothing reads as paint.
+    mesh.castShadow = spec.id === 'body' || !!spec.cast;
+    mesh.userData.shut = !!spec.shut;
+    // how far this feature may slide when the character looks somewhere, in
+    // its own plane. A pupil gets most of its white; a white eye gets
+    // almost nothing. Absent means "use the default for a whole eye".
+    if (spec.travel) mesh.userData.travel = spec.travel;
+    // how far a lid slides DOWN as the eye closes
+    if (spec.lidDrop) mesh.userData.lidDrop = spec.lidDrop;
+    // or how far it ROLLS — the ball eye's hemisphere cap pivots about
+    // the ball's centre instead of sliding, in radians
+    if (spec.lidRoll) mesh.userData.lidRoll = spec.lidRoll;
+    // where a pupil parks in its white. The blink pulls it back to
+    // centre, because the white squashes about the EYE's middle and a
+    // pupil left up at the top would be squashed about its own and
+    // slide straight out of the closing lid.
+    if (spec.anchorY) mesh.userData.anchorY = spec.anchorY;
+
+    // frame meshes live on the GROUP and hold still under the gaze;
+    // everything else is on the head and turns with it. Specs are
+    // authored in world y, so a head child gives the pivot's share back.
+    if (spec.frame) {
+      group.add(mesh);
+    } else {
+      mesh.position.y -= L.cy;
+      head.add(mesh);
+      // ...and only what is ON the head is a face: the animator slides
+      // its entries with the gaze, and a torso that slid would walk
+      if (spec.id !== 'body') face[spec.id] = mesh;
+    }
+    verts += geo.attributes.position.count;
+  }
+
+  // WHAT WAS ACTUALLY BUILT. `L.H` is the BODY's height and nothing
+  // else, so a page that fits a character by it is fitting the head and
+  // ignoring whatever is standing on top of it — a bunny came out 1.76×
+  // taller than its cell believed and grew into the row above. Ears,
+  // horns and a dropped maw all live out here, and every one of them
+  // is inside these bounds.
+  const box = new THREE.Box3();
+  group.updateMatrixWorld(true);
+  group.traverse(child => {
+    if (!child.isMesh) return;
+    child.geometry.computeBoundingBox();
+    box.union(child.geometry.boundingBox.clone().applyMatrix4(child.matrixWorld));
+  });
+  const bounds = {
+    w: box.max.x - box.min.x, h: box.max.y - box.min.y,
+    cy: (box.min.y + box.max.y) / 2,     // the character's real middle, not the head's
+    minY: box.min.y, maxY: box.max.y,
+  };
+
+  return {
+    group, head, face, P, L, bounds,
+    stats: { buildMs: Math.round(performance.now() - t0), verts, meshes: specs.length },
+  };
+}