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
13.3 KB
Raw Blame
// ACS engine — GLB writer (skinned + animated). Author: Ariescar.
// glTF 2.0 binary: joint node tree, skin (IBM), per-vertex JOINTS_0/WEIGHTS_0,
// LINEAR-sampled animations, per-material primitives, flat PBR materials.
'use strict';
const fs = require('fs');

const { smoothSplit } = require('./normals.js');

function triangulate(faces) {
  const out = [];
  for (const f of faces) {
    if (f.length === 3) out.push(f);
    else if (f.length === 4) out.push([f[0], f[1], f[2]], [f[0], f[2], f[3]]);
  }
  return out;
}
function hex2rgb(h) {
  const x = parseInt(h.replace('#', ''), 16);
  const s = c => Math.pow(c / 255, 2.2);
  return [s((x >> 16) & 255), s((x >> 8) & 255), s(x & 255)];
}

// build = { meshes, skeleton?, ibm?, anims? }
//   meshes: [{material,color,rough,metal,V,F, skin?: [ [[jointName,w],...] per vertex ]}]
//   skeleton: { joints:[{name,pos,parent}], index:{} }  ibm: Float32Array(16*n)
//   anims: [{name,duration,channels:[{joint,path,times,values}]}]
// ── L8: soften the shipped NORMAL toward the bone field ───────────────────
// The other seven layers bake into COLOR_0, which a viewer is free to ignore.
// This one is different: NORMAL is part of the file and the user's lighting
// cannot opt out of it. Verified in the lab against a blank viewer — one
// directional light, stock material, none of our vertex colours — the shape
// visibly softened, at 29-43° median from the mesh normals.
//
// FLESH ONLY, and that is a deliberate departure from the lab's settled value
// of "hardware 50%". The lab needed a fake normal on hardware because its
// smooth-normal path did not compute hardware at all — it substituted raw mesh
// normals, so the only way to soften a plate was the bone field. This engine
// does not have that hole: `smoothSplit` gives every piece angle-weighted
// normals with real creases. Importing the workaround would import the cost
// the lab measured with it — on hardware the bone field pointed at the BACK of
// the surface for 28-44% of vertices, because a plate's facing has nothing to
// do with where the nearest bone is. Flesh has no such problem: skin wraps
// bone, so the direction from bone to vertex IS roughly the surface normal.
function boneField(V, skin, sk) {
  return V.map((v, i) => {
    const infl = skin && skin[i];
    if (!infl || !infl.length) return null;
    let px = 0, py = 0, pz = 0, w = 0;
    for (const [j, wt] of infl) {
      const k = sk.index ? sk.index[j] : undefined;
      if (k == null) continue;
      const q = sk.joints[k].pos;
      px += q[0] * wt; py += q[1] * wt; pz += q[2] * wt; w += wt;
    }
    if (!w) return null;
    const d = [v[0] - px / w, v[1] - py / w, v[2] - pz / w];
    const L = Math.hypot(d[0], d[1], d[2]);
    return L > 1e-9 ? [d[0] / L, d[1] / L, d[2] / L] : null;
  });
}

const L8_MOVED = [];
function writeGLB(build, outPath, opts = {}) {
  L8_MOVED.length = 0;
  const { meshes, skeleton, ibm, anims } = build;
  const names = opts.names || {};   // internal joint name → public export name
  const bufs = []; let byteLen = 0;
  const pushBuf = (ab) => {
    const pad = (4 - (ab.byteLength % 4)) % 4;
    const view = { byteOffset: byteLen, byteLength: ab.byteLength };
    bufs.push(Buffer.from(ab.buffer ? ab.buffer.slice(ab.byteOffset, ab.byteOffset + ab.byteLength) : ab));
    if (pad) bufs.push(Buffer.alloc(pad));
    byteLen += ab.byteLength + pad;
    return view;
  };
  const gltf = {
    asset: Object.assign({ version: '2.0', generator: 'acs-engine' }, opts.asset || {}),
    scenes: [{ nodes: [] }], scene: 0,
    nodes: [], meshes: [{ name: 'creature', primitives: [] }],
    materials: [], accessors: [], bufferViews: [], buffers: [],
  };
  const addAccessor = (arr, ctype, type, target, minmax) => {
    const bv = pushBuf(arr);
    gltf.bufferViews.push(target ? { buffer: 0, ...bv, target } : { buffer: 0, ...bv });
    const acc = { bufferView: gltf.bufferViews.length - 1, componentType: ctype,
      count: arr.length / ({ SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT4: 16 }[type]), type };
    if (minmax) { acc.min = minmax[0]; acc.max = minmax[1]; }
    gltf.accessors.push(acc);
    return gltf.accessors.length - 1;
  };

  // ── joint nodes ──
  let jointNodeBase = 0; let skinIndex;
  if (skeleton) {
    const { localTranslations } = require('./skeleton.js');
    const locals = localTranslations(skeleton);
    jointNodeBase = gltf.nodes.length;
    skeleton.joints.forEach((j, i) => {
      gltf.nodes.push({ name: names[j.name] || j.name, translation: locals[i] });
    });
    skeleton.joints.forEach((j, i) => {
      if (j.parent >= 0) {
        const pn = gltf.nodes[jointNodeBase + j.parent];
        (pn.children = pn.children || []).push(jointNodeBase + i);
      } else gltf.scenes[0].nodes.push(jointNodeBase + i);
    });
    const ibmAcc = addAccessor(ibm, 5126, 'MAT4');
    gltf.skins = [{ name: 'creature_rig', joints: skeleton.joints.map((_, i) => jointNodeBase + i),
      inverseBindMatrices: ibmAcc }];
    skinIndex = 0;
  }

  // ── mesh node ──
  const meshNode = { name: 'creature', mesh: 0 };
  if (skinIndex !== undefined) meshNode.skin = skinIndex;
  gltf.nodes.push(meshNode);
  gltf.scenes[0].nodes.push(gltf.nodes.length - 1);

  // ── primitives (merged: one primitive + one material per distinct material) ──
  // Mirrored twins and repeated parts share a palette entry; without merging
  // every mesh ships its own primitive+material copy (the 67-material class).
  // Semantic part names are the palette keys, so merging by material signature
  // loses nothing the judge needs.
  // Where each PART ended up in the merged buffers. A material is a class and is
  // shared on purpose, so the material name cannot answer "which part is this" —
  // the same `paw` material can sit on a foot pad and on a nose-leaf. The merge
  // knows exactly which vertices came from which part, so it writes that down
  // instead of throwing it away: one row per part, [first, count] into its own
  // primitive. Nothing renders differently; the identity simply survives.
  const spans = [];
  const groups = new Map();
  for (const m of meshes) {
    let tris = triangulate(m.F);
    // Smoothing angle: faces meeting at a vertex are averaged when they sit
    // within `smoothAngle` of each other, and the vertex is duplicated only
    // where it really carries two smoothing groups. `faceted: true` is just
    // smoothAngle 0 (every face its own group). Default lives in cli.js.
    const deg = m.faceted ? 0 : (m.smoothAngle ?? 50);
    const r = smoothSplit(m.V, tris, deg, { C: m.C, skin: m.skin, UV: m.UV });
    m.V = r.V; if (m.C) m.C = r.C; if (m.skin) m.skin = r.skin; if (m.UV) m.UV = r.UV;
    tris = r.tris;
    let N = r.N;
    // L8, after the crease split so the blend lands on the shipped vertices
    const l8 = opts.boneNormals;
    if (l8 && m._cls === 'flesh' && skeleton && m.skin) {
      const F = boneField(m.V, m.skin, skeleton);
      let moved = 0;
      N = N.map((n, i) => {
        const f = F[i];
        if (!f) return n;
        // never let the blend cross to the back of the surface — a normal that
        // has flipped is worse than one that was never softened
        if (n[0] * f[0] + n[1] * f[1] + n[2] * f[2] <= 0) return n;
        const a = l8;
        const b = [n[0] * (1 - a) + f[0] * a, n[1] * (1 - a) + f[1] * a, n[2] * (1 - a) + f[2] * a];
        const L = Math.hypot(b[0], b[1], b[2]);
        if (L < 1e-9) return n;
        moved++;
        return [b[0] / L, b[1] / L, b[2] / L];
      });
      if (moved) L8_MOVED.push([m.material, moved, N.length]);
    }
    const key = [m.material, m.color, m.rough ?? 0.9, m.metal ?? 0, !!m.doubleSided, !!m.C, !!m.UV].join('|');
    let g = groups.get(key);
    if (!g) groups.set(key, g = { m, V: [], N: [], C: m.C ? [] : null, UV: m.UV ? [] : null,
      skin: m.skin ? [] : null, tris: [] });
    const off = g.V.length;
    // a mirrored twin is a different piece of geometry and gets a different id;
    // parts already carry ".R", volumes deliberately keep their source chain name
    // (checks compare the twin against the original by it), so it is added here
    spans.push({ id: (m.part || (m.chain && m._mirrorSrc ? m.chain + '.R' : m.chain) || null),
                 material: m.material, _key: key, first: off, count: m.V.length });
    g.V.push(...m.V); g.N.push(...N);
    if (g.C && m.C) g.C.push(...m.C);
    if (g.UV && m.UV) g.UV.push(...m.UV);
    if (g.skin && m.skin) g.skin.push(...m.skin);
    for (const t of tris) g.tris.push([t[0] + off, t[1] + off, t[2] + off]);
  }
  const primOf = new Map();
  for (const [gkey, g] of groups) {
    primOf.set(gkey, gltf.meshes[0].primitives.length);
    const { m } = g;
    // Portability: the hue lives in baseColorFactor, COLOR_0 carries only the
    // shading multiplier. With baseColorFactor white (the old way) EVERY colour
    // in the file lived in vertex colours, so any viewer that does not apply
    // COLOR_0 — and there are many — rendered the creature pure white. Splitting
    // it is lossless where COLOR_0 IS applied (base × vertex reproduces the same
    // value per channel, since base is the per-channel MAXIMUM and the vertex
    // ratios are therefore ≤ 1) and degrades to "right hue, flat shading" where
    // it is not. Observed in the field: a creature published to a gallery came
    // back white-and-black.
    let base = [1, 1, 1, 1];
    if (g.C) {
      // NEW arrays, never in place: a vertex-colour array can be referenced from
      // more than one vertex (flat fills, crease splits), and dividing in place
      // would scale a shared object twice and shift the colour.
      const mx = [0, 1, 2].map(k => Math.max(1e-4, ...g.C.map(c => c[k])));
      g.C = g.C.map(c => [Math.min(1, c[0] / mx[0]), Math.min(1, c[1] / mx[1]), Math.min(1, c[2] / mx[2])]);
      base = [mx[0], mx[1], mx[2], 1];
    }
    const mins = [0,1,2].map(k => Math.min(...g.V.map(v => v[k])));
    const maxs = [0,1,2].map(k => Math.max(...g.V.map(v => v[k])));
    const attrs = {
      POSITION: addAccessor(new Float32Array(g.V.flat()), 5126, 'VEC3', 34962, [mins, maxs]),
      NORMAL: addAccessor(new Float32Array(g.N.flat()), 5126, 'VEC3', 34962),
    };
    if (g.C) attrs.COLOR_0 = addAccessor(new Float32Array(g.C.flat()), 5126, 'VEC3', 34962);
    if (g.UV) attrs.TEXCOORD_0 = addAccessor(new Float32Array(g.UV.flat()), 5126, 'VEC2', 34962);
    if (skeleton && g.skin) {
      const J = new Uint16Array(g.V.length * 4); const W = new Float32Array(g.V.length * 4);
      g.skin.forEach((infl, vi) => {
        let tot = 0; infl.slice(0, 4).forEach(([, w]) => tot += w);
        infl.slice(0, 4).forEach(([jn, w], k) => {
          const ji = skeleton.index[jn];
          if (ji === undefined) throw new Error(`skin references unknown joint "${jn}"`);
          J[vi * 4 + k] = ji; W[vi * 4 + k] = w / (tot || 1);
        });
      });
      attrs.JOINTS_0 = addAccessor(J, 5123, 'VEC4', 34962);
      attrs.WEIGHTS_0 = addAccessor(W, 5126, 'VEC4', 34962);
    }
    const idxAcc = addAccessor(new Uint32Array(g.tris.flat()), 5125, 'SCALAR', 34963);
    const mi = gltf.materials.length;
    const mat = { name: m.material, pbrMetallicRoughness: {
      baseColorFactor: g.C ? base : [...hex2rgb(m.color), 1],
      metallicFactor: m.metal ?? 0, roughnessFactor: m.rough ?? 0.9 } };
    if (m.doubleSided) mat.doubleSided = true;   // zero-thickness membranes
    gltf.materials.push(mat);
    gltf.meshes[0].primitives.push({ attributes: attrs, indices: idxAcc, material: mi });
  }

  // ── animations ──
  if (anims && anims.length && skeleton) {
    gltf.animations = anims.map(a => {
      const samplers = []; const channels = [];
      for (const ch of a.channels) {
        const tAcc = addAccessor(new Float32Array(ch.times), 5126, 'SCALAR', null,
          [[Math.min(...ch.times)], [Math.max(...ch.times)]]);
        const vAcc = addAccessor(new Float32Array(ch.values), 5126, ch.path === 'rotation' ? 'VEC4' : 'VEC3');
        samplers.push({ input: tAcc, output: vAcc, interpolation: 'LINEAR' });
        channels.push({ sampler: samplers.length - 1,
          target: { node: jointNodeBase + skeleton.index[ch.joint], path: ch.path } });
      }
      return { name: a.name, samplers, channels };
    });
  }

  gltf.buffers.push({ byteLength: byteLen });
  const bin = Buffer.concat(bufs);
  if (opts.spans !== false) {
    for (const s of spans) { s.primitive = primOf.get(s._key); delete s._key; }
    gltf.asset.extras = Object.assign({}, gltf.asset.extras, { part_spans: spans });
  }

  let js = Buffer.from(JSON.stringify(gltf)); const jpad = (4 - (js.length % 4)) % 4;
  if (jpad) js = Buffer.concat([js, Buffer.alloc(jpad, 0x20)]);
  const total = 12 + 8 + js.length + 8 + bin.length;
  const head = Buffer.alloc(12); head.write('glTF'); head.writeUInt32LE(2, 4); head.writeUInt32LE(total, 8);
  const jh = Buffer.alloc(8); jh.writeUInt32LE(js.length, 0); jh.writeUInt32LE(0x4E4F534A, 4);
  const bh = Buffer.alloc(8); bh.writeUInt32LE(bin.length, 0); bh.writeUInt32LE(0x004E4942, 4);
  // The README's own first command writes to out/wolf.glb, and a fresh clone has
  // no out/ — without this the very first build a newcomer runs dies on ENOENT
  // after doing all the work.
  const dir = require('path').dirname(outPath);
  if (dir && dir !== '.') fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(outPath, Buffer.concat([head, jh, js, bh, bin]));
  return total;
}

module.exports = { writeGLB, triangulate, L8_MOVED };