Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// three.ws Forge — deterministic generative 3D sculpture engine. Zero deps.
//
// A seed string → a one-of-one 3D form, synthesized from the Gielis
// superformula, encoded as a real binary GLB (positions, normals, gradient
// vertex colors, a PBR material). Same seed always yields identical bytes;
// a one-character change yields a completely different sculpture.
//
// Nothing here is random at runtime — all variation is derived from a hash of
// the seed, so the API is pure and cacheable.
// ── Deterministic PRNG (xmur3 seed → mulberry32) ─────────────────────────────
function xmur3(str) {
let h = 1779033703 ^ str.length;
for (let i = 0; i < str.length; i++) {
h = Math.imul(h ^ str.charCodeAt(i), 3432918353);
h = (h << 13) | (h >>> 19);
}
return () => {
h = Math.imul(h ^ (h >>> 16), 2246822507);
h = Math.imul(h ^ (h >>> 13), 3266489909);
return (h ^= h >>> 16) >>> 0;
};
}
function mulberry32(a) {
return () => {
a |= 0; a = (a + 0x6d2b79f5) | 0;
let t = Math.imul(a ^ (a >>> 15), 1 | a);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
function makeRng(seed) {
const s = xmur3(String(seed));
return mulberry32(s());
}
// ── Palettes / finishes (seed-selected) ──────────────────────────────────────
// Each finish carries PBR character + a 2-stop gradient (hue base, hsl).
const FINISHES = [
{ name: 'Chrome', metallic: 1.0, roughness: 0.12, emissive: 0.0, hue: 210, sat: 0.06, glow: false },
{ name: 'Obsidian', metallic: 0.6, roughness: 0.18, emissive: 0.0, hue: 270, sat: 0.45, glow: false },
{ name: 'Plasma', metallic: 0.2, roughness: 0.35, emissive: 2.4, hue: 320, sat: 0.95, glow: true },
{ name: 'Jade', metallic: 0.1, roughness: 0.28, emissive: 0.0, hue: 150, sat: 0.6, glow: false },
{ name: 'Gold', metallic: 1.0, roughness: 0.22, emissive: 0.0, hue: 45, sat: 0.85, glow: false },
{ name: 'Aurora', metallic: 0.35, roughness: 0.3, emissive: 1.6, hue: 175, sat: 0.9, glow: true },
{ name: 'Magma', metallic: 0.3, roughness: 0.45, emissive: 2.2, hue: 18, sat: 1.0, glow: true },
{ name: 'Frost', metallic: 0.5, roughness: 0.08, emissive: 0.2, hue: 195, sat: 0.4, glow: false },
];
const FORM_NAMES = ['Orb', 'Bloom', 'Star', 'Shard', 'Helix', 'Coral', 'Lotus', 'Spire', 'Nimbus', 'Vortex', 'Prism', 'Seed'];
function hslToRgb(h, s, l) {
h = ((h % 360) + 360) % 360 / 360;
const a = s * Math.min(l, 1 - l);
const f = (n) => {
const k = (n + h * 12) % 12;
return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
};
return [f(0), f(8), f(4)];
}
// ── Trait derivation ─────────────────────────────────────────────────────────
function deriveTraits(seed) {
const rng = makeRng(seed);
const pick = (arr) => arr[Math.floor(rng() * arr.length)];
const range = (lo, hi) => lo + rng() * (hi - lo);
// Two superformula profiles (latitude + longitude). Curated ranges keep
// shapes striking rather than degenerate.
const m1 = Math.floor(range(2, 17));
const m2 = Math.floor(range(2, 17));
const prof = () => ({
n1: range(0.3, 3.2),
n2: range(0.4, 5.5),
n3: range(0.4, 5.5),
});
const p1 = prof();
const p2 = prof();
const twist = range(-1.4, 1.4);
const finish = pick(FINISHES);
const hueShift = Math.floor(range(0, 40)) - 20;
// Rarity: rare params (high symmetry + glow + extreme exponents) score higher.
let rarity = 0;
rarity += Math.max(m1, m2) * 2.2;
rarity += finish.glow ? 22 : 0;
rarity += p1.n1 < 0.7 || p2.n1 < 0.7 ? 16 : 0; // spiky
rarity += Math.abs(twist) > 1.0 ? 12 : 0;
rarity += rng() * 14;
rarity = Math.min(100, Math.round(rarity));
const tier = rarity >= 85 ? 'Mythic' : rarity >= 70 ? 'Legendary' : rarity >= 50 ? 'Epic' : rarity >= 30 ? 'Rare' : 'Common';
const formName = FORM_NAMES[(m1 + m2) % FORM_NAMES.length];
return {
seed: String(seed),
name: `${finish.name} ${formName}`,
form: formName,
finish: finish.name,
symmetry: { lat: m1, lon: m2 },
spikiness: Math.round((1 / Math.min(p1.n1, p2.n1)) * 100) / 100,
twist: Math.round(twist * 100) / 100,
rarity,
tier,
_p: { m1, m2, p1, p2, twist, finish, hueShift },
};
}
// ── Superformula + mesh synthesis ────────────────────────────────────────────
function superR(angle, m, n1, n2, n3) {
const t1 = Math.pow(Math.abs(Math.cos((m * angle) / 4)), n2);
const t2 = Math.pow(Math.abs(Math.sin((m * angle) / 4)), n3);
let r = Math.pow(t1 + t2, -1 / n1);
if (!isFinite(r)) r = 0;
return Math.min(r, 8); // clamp runaway spikes
}
function buildMesh(traits, resolution) {
const { m1, m2, p1, p2, twist, finish, hueShift } = traits._p;
const lat = resolution; // phi: -pi/2 .. pi/2
const lon = resolution * 2; // theta: -pi .. pi
const cols = lon + 1;
const rows = lat + 1;
const vCount = rows * cols;
const positions = new Float32Array(vCount * 3);
const normals = new Float32Array(vCount * 3);
const colors = new Uint8Array(vCount * 4);
const min = [Infinity, Infinity, Infinity];
const max = [-Infinity, -Infinity, -Infinity];
let v = 0;
for (let i = 0; i < rows; i++) {
const phi = -Math.PI / 2 + (i / lat) * Math.PI;
const r2 = superR(phi, m2, p2.n1, p2.n2, p2.n3);
for (let j = 0; j < cols; j++) {
const theta = -Math.PI + (j / lon) * 2 * Math.PI;
// twist couples longitude into latitude for spiral character
const r1 = superR(theta + twist * phi, m1, p1.n1, p1.n2, p1.n3);
const cx = r1 * Math.cos(theta) * r2 * Math.cos(phi);
const cz = r1 * Math.sin(theta) * r2 * Math.cos(phi);
const cy = r2 * Math.sin(phi);
const k = v * 3;
positions[k] = cx; positions[k + 1] = cy; positions[k + 2] = cz;
if (cx < min[0]) min[0] = cx; if (cy < min[1]) min[1] = cy; if (cz < min[2]) min[2] = cz;
if (cx > max[0]) max[0] = cx; if (cy > max[1]) max[1] = cy; if (cz > max[2]) max[2] = cz;
v++;
}
}
// Recenter + normalize to maxDim = 2 for a friendly default scale.
const center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
const span = Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2]) || 1;
const scale = 2 / span;
for (let p = 0; p < vCount; p++) {
positions[p * 3] = (positions[p * 3] - center[0]) * scale;
positions[p * 3 + 1] = (positions[p * 3 + 1] - center[1]) * scale;
positions[p * 3 + 2] = (positions[p * 3 + 2] - center[2]) * scale;
}
const nmin = [Infinity, Infinity, Infinity];
const nmax = [-Infinity, -Infinity, -Infinity];
for (let p = 0; p < vCount; p++) {
for (let a = 0; a < 3; a++) {
const val = positions[p * 3 + a];
if (val < nmin[a]) nmin[a] = val;
if (val > nmax[a]) nmax[a] = val;
}
}
// Indices (two triangles per grid quad).
const quadCount = lat * lon;
const indices = new Uint32Array(quadCount * 6);
let t = 0;
for (let i = 0; i < lat; i++) {
for (let j = 0; j < lon; j++) {
const a = i * cols + j;
const b = a + cols;
indices[t++] = a; indices[t++] = b; indices[t++] = a + 1;
indices[t++] = a + 1; indices[t++] = b; indices[t++] = b + 1;
}
}
// Accumulate face normals → smooth vertex normals.
for (let f = 0; f < indices.length; f += 3) {
const ia = indices[f] * 3, ib = indices[f + 1] * 3, ic = indices[f + 2] * 3;
const ax = positions[ia], ay = positions[ia + 1], az = positions[ia + 2];
const ux = positions[ib] - ax, uy = positions[ib + 1] - ay, uz = positions[ib + 2] - az;
const wx = positions[ic] - ax, wy = positions[ic + 1] - ay, wz = positions[ic + 2] - az;
const nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx;
normals[ia] += nx; normals[ia + 1] += ny; normals[ia + 2] += nz;
normals[ib] += nx; normals[ib + 1] += ny; normals[ib + 2] += nz;
normals[ic] += nx; normals[ic + 1] += ny; normals[ic + 2] += nz;
}
for (let p = 0; p < vCount; p++) {
const k = p * 3;
const len = Math.hypot(normals[k], normals[k + 1], normals[k + 2]) || 1;
normals[k] /= len; normals[k + 1] /= len; normals[k + 2] /= len;
}
// Gradient vertex colors by normalized height, in the finish's hue family.
const hSpan = nmax[1] - nmin[1] || 1;
for (let p = 0; p < vCount; p++) {
const h = (positions[p * 3 + 1] - nmin[1]) / hSpan; // 0..1 bottom→top
const hue = finish.hue + hueShift + h * 40;
const light = 0.32 + h * 0.42;
const [r, g, bl] = hslToRgb(hue, finish.sat, light);
const c = p * 4;
colors[c] = Math.round(r * 255);
colors[c + 1] = Math.round(g * 255);
colors[c + 2] = Math.round(bl * 255);
colors[c + 3] = 255;
}
return { positions, normals, colors, indices, vCount, min: nmin, max: nmax };
}
// ── GLB binary encoder (hand-written, zero deps) ─────────────────────────────
function align4(n) { return (n + 3) & ~3; }
function encodeGlb(mesh, traits) {
const { positions, normals, colors, indices, vCount } = mesh;
const { finish } = traits._p;
// BIN layout — every accessor is naturally 4-byte aligned.
const idxBytes = indices.byteLength;
const posBytes = positions.byteLength;
const normBytes = normals.byteLength;
const colBytes = colors.byteLength;
const binLen = idxBytes + posBytes + normBytes + colBytes;
const bin = Buffer.alloc(binLen);
let off = 0;
Buffer.from(indices.buffer, indices.byteOffset, idxBytes).copy(bin, off); const idxOff = off; off += idxBytes;
Buffer.from(positions.buffer, positions.byteOffset, posBytes).copy(bin, off); const posOff = off; off += posBytes;
Buffer.from(normals.buffer, normals.byteOffset, normBytes).copy(bin, off); const normOff = off; off += normBytes;
Buffer.from(colors.buffer, colors.byteOffset, colBytes).copy(bin, off); const colOff = off; off += colBytes;
const baseColor = hslToRgb(finish.hue + traits._p.hueShift, finish.sat * 0.8, 0.6);
const emissive = finish.glow ? hslToRgb(finish.hue, finish.sat, 0.5).map((c) => c * 0.6) : [0, 0, 0];
const gltf = {
asset: { version: '2.0', generator: 'three.ws Forge' },
scene: 0,
scenes: [{ nodes: [0] }],
nodes: [{ mesh: 0, name: traits.name }],
meshes: [{
name: traits.name,
primitives: [{
attributes: { POSITION: 1, NORMAL: 2, COLOR_0: 3 },
indices: 0,
material: 0,
mode: 4,
}],
}],
materials: [{
name: finish.name,
pbrMetallicRoughness: {
baseColorFactor: [baseColor[0], baseColor[1], baseColor[2], 1],
metallicFactor: finish.metallic,
roughnessFactor: finish.roughness,
},
emissiveFactor: emissive,
doubleSided: true,
...(finish.glow ? { extensions: { KHR_materials_emissive_strength: { emissiveStrength: finish.emissive } } } : {}),
}],
...(finish.glow ? { extensionsUsed: ['KHR_materials_emissive_strength'] } : {}),
bufferViews: [
{ buffer: 0, byteOffset: idxOff, byteLength: idxBytes, target: 34963 },
{ buffer: 0, byteOffset: posOff, byteLength: posBytes, target: 34962 },
{ buffer: 0, byteOffset: normOff, byteLength: normBytes, target: 34962 },
{ buffer: 0, byteOffset: colOff, byteLength: colBytes, target: 34962 },
],
accessors: [
{ bufferView: 0, componentType: 5125, count: indices.length, type: 'SCALAR' },
{ bufferView: 1, componentType: 5126, count: vCount, type: 'VEC3', min: mesh.min, max: mesh.max },
{ bufferView: 2, componentType: 5126, count: vCount, type: 'VEC3' },
{ bufferView: 3, componentType: 5121, normalized: true, count: vCount, type: 'VEC4' },
],
buffers: [{ byteLength: binLen }],
};
const jsonBuf = Buffer.from(JSON.stringify(gltf), 'utf8');
const jsonPad = align4(jsonBuf.length) - jsonBuf.length;
const binPad = align4(bin.length) - bin.length;
const total = 12 + 8 + jsonBuf.length + jsonPad + 8 + bin.length + binPad;
const out = Buffer.alloc(total);
let o = 0;
out.writeUInt32LE(0x46546c67, o); o += 4; // magic "glTF"
out.writeUInt32LE(2, o); o += 4; // version
out.writeUInt32LE(total, o); o += 4; // total length
// JSON chunk
out.writeUInt32LE(jsonBuf.length + jsonPad, o); o += 4;
out.writeUInt32LE(0x4e4f534a, o); o += 4; // "JSON"
jsonBuf.copy(out, o); o += jsonBuf.length;
for (let i = 0; i < jsonPad; i++) out[o++] = 0x20; // space pad
// BIN chunk
out.writeUInt32LE(bin.length + binPad, o); o += 4;
out.writeUInt32LE(0x004e4942, o); o += 4; // "BIN\0"
bin.copy(out, o); o += bin.length;
for (let i = 0; i < binPad; i++) out[o++] = 0x00;
return out;
}
// ── Public API ───────────────────────────────────────────────────────────────
export function forgeTraits(seed) {
const t = deriveTraits(seed);
const { _p, ...pub } = t;
return pub;
}
export function forgeGlb(seed, resolution = 120) {
// Ceiling keeps the base64 GLB under the Lambda Function URL 6 MB response cap.
const res = Math.max(24, Math.min(190, Math.floor(resolution) || 120));
const traits = deriveTraits(seed);
const mesh = buildMesh(traits, res);
const glb = encodeGlb(mesh, traits);
const { _p, ...pub } = traits;
return {
glb,
stats: { vertices: mesh.vCount, triangles: mesh.indices.length / 3, bytes: glb.length, resolution: res },
traits: pub,
};
}
// Raw mesh + full traits (incl. private finish params) for the software
// renderer that produces social-card preview images.
export function forgeRaw(seed, resolution = 90) {
const res = Math.max(24, Math.min(220, Math.floor(resolution) || 90));
const traits = deriveTraits(seed);
const mesh = buildMesh(traits, res);
return { mesh, traits };
}