You can now generate creatures directly within your project. Drop the open-source into your Agent, and start prompting what you want.
JavaScript
// 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 };