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
// The GPU particle engine behind /dissolve.
//
// Every particle lives in a texel of two float textures (position, velocity).
// Each frame two fullscreen passes advance them (velocity, then position), and
// a Points draw reads the result straight from those textures, so a million
// particles never touch the CPU after the shapes are uploaded.
//
// Shapes arrive as ShapeClouds (src/dissolve/shape.js). Each one is Morton
// sorted over the shared stage box so particle i of shape A and particle i of
// shape B sit in the same relative place; a morph then moves feet to feet and
// head to head, with a per-particle stagger that turns the blend into a ripple.
import * as THREE from 'three';
import { mortonOrder, mulberry32 } from './sample-core.js';
export const STAGE_MIN = [-1.6, -1, -1.6];
export const STAGE_MAX = [1.6, 1, 1.6];
const MAX_WAVES = 4;
export const TOOL = { none: 0, gravity: 1, vortex: 2 };
export const DEFAULT_PARAMS = {
spring: 16,
damp: 5.2,
turb: 0.35,
arc: 0.6,
stagger: 0.7,
size: 1,
bright: 0.55,
gravity: 0,
};
const FULLSCREEN_VERT = /* glsl */ `
void main() { gl_Position = vec4(position.xy, 0.0, 1.0); }
`;
const COMMON_GLSL = /* glsl */ `
float hash11(float n) { return fract(sin(n) * 43758.5453123); }
// Per-particle morph progress: the stagger makes the blend a ripple instead
// of one flat cross-fade.
float progressFor(float mixv, float stagger, float seed) {
float p = clamp(mixv * (1.0 + stagger) - stagger * seed, 0.0, 1.0);
return p * p * (3.0 - 2.0 * p);
}
`;
const VELOCITY_FRAG = /* glsl */ `
uniform vec2 uRes;
uniform sampler2D tPos, tVel, tA, tB;
uniform float uDt, uTime, uMix, uStagger, uSpring, uDamp, uTurb, uGravity, uFloor, uBass, uMid, uArc;
uniform vec4 uAttr; // xyz world point, w strength
uniform float uMode; // 0 off, 1 gravity well, 2 vortex
uniform vec3 uAxis; // camera forward: spin axis for the well, jet axis
uniform vec4 uWave[${MAX_WAVES}]; // xyz centre, w birth time (negative = unused)
uniform float uWaveStrength;
${COMMON_GLSL}
// Divergence-free flow: the curl of a sum of sine potentials. Particles swirl
// without bunching up or thinning out, which is what makes it read as fluid.
vec3 flow(vec3 p, float t) {
vec3 q = p * 1.35;
vec3 c1 = vec3(-cos(q.z * 1.0 + t * 1.1), -cos(q.x * 1.0 + t * 0.9), -cos(q.y * 1.0 + t * 1.0));
vec3 r = p * 2.6 + vec3(1.7, 9.2, 3.1);
vec3 c2 = vec3(-cos(r.y * 1.0 - t * 0.7), -cos(r.z * 1.0 + t * 1.3), -cos(r.x * 1.0 - t * 0.5));
return c1 + 0.5 * c2;
}
void main() {
vec2 uv = gl_FragCoord.xy / uRes;
vec4 pp = texture2D(tPos, uv);
vec4 vv = texture2D(tVel, uv);
vec3 pos = pp.xyz;
vec3 vel = vv.xyz;
vec4 a = texture2D(tA, uv);
vec4 b = texture2D(tB, uv);
float seed = a.w;
float prog = progressFor(uMix, uStagger, seed);
vec3 tgt = mix(a.xyz, b.xyz, prog);
float flight = sin(3.14159265 * prog);
vec3 travel = b.xyz - a.xyz;
vec3 side = cross(travel, vec3(0.0, 1.0, 0.0));
side = side / (length(side) + 1e-4);
tgt += side * flight * uArc * (seed - 0.5) * 1.4 * length(travel) * 0.5;
tgt.y += flight * uArc * (hash11(seed * 91.7) - 0.25) * 0.9;
tgt += tgt * uBass * 0.22;
vec3 acc = uSpring * (tgt - pos);
acc += flow(pos, uTime * 0.6) * (uTurb + uMid * 5.0) * 3.0;
acc -= uDamp * vel;
acc.y -= uGravity;
if (uMode > 0.5 && uAttr.w > 0.0) {
vec3 d = uAttr.xyz - pos;
if (uMode < 1.5) {
float r2 = dot(d, d) + 0.02;
float inv = inversesqrt(r2);
vec3 dir = d * inv;
float pull = min(uAttr.w * 3.2 / r2, 140.0);
acc += dir * pull;
acc += cross(uAxis, dir) * min(uAttr.w * 5.0 / (r2 + 0.08), 60.0);
acc -= uSpring * (tgt - pos) * clamp(uAttr.w * 0.8, 0.0, 0.92);
if (r2 < 0.014) {
// Past the horizon: thrown out along the spin axis as a relativistic jet.
float sgn = hash11(pos.x * 13.1 + pos.y * 7.7 + pos.z * 3.3 + uTime) > 0.5 ? 1.0 : -1.0;
float spd = 5.0 + 7.0 * hash11(pos.z * 17.3 + uTime * 1.7);
vel = uAxis * sgn * spd + flow(pos * 3.0, uTime) * 0.8;
gl_FragColor = vec4(vel, 1.0);
return;
}
} else {
vec3 rel = pos - uAttr.xyz;
float rr = length(rel.xz);
float fall = exp(-rr * rr / 1.6);
acc += vec3(-rel.z, 0.0, rel.x) / (rr + 0.25) * fall * uAttr.w * 34.0;
acc.y += fall * uAttr.w * 9.0;
acc -= uSpring * (tgt - pos) * fall * 0.85;
}
}
for (int i = 0; i < ${MAX_WAVES}; i++) {
vec4 w = uWave[i];
if (w.w < 0.0) continue;
float age = uTime - w.w;
if (age < 0.0 || age > 3.5) continue;
vec3 dd = pos - w.xyz;
float r = length(dd) + 1e-4;
float band = exp(-pow((r - age * 3.4) / 0.3, 2.0));
float fade = 1.0 - age / 3.5;
acc += dd / r * band * fade * uWaveStrength * 90.0;
acc.y += band * fade * uWaveStrength * 14.0;
acc -= uSpring * (tgt - pos) * band * 0.9;
}
vel += acc * uDt;
if (uGravity > 0.0 && pos.y <= uFloor + 0.002 && vel.y < 0.0) {
vel.y = -vel.y * 0.46;
vel.xz *= 0.9;
}
float sp = length(vel);
if (sp > 16.0) vel *= 16.0 / sp;
float heat = max(vv.w * exp(-uDt * 2.2), min(sp / 7.0, 1.0));
gl_FragColor = vec4(vel, heat);
}
`;
const POSITION_FRAG = /* glsl */ `
uniform vec2 uRes;
uniform sampler2D tPos, tVel;
uniform float uDt, uGravity, uFloor;
void main() {
vec2 uv = gl_FragCoord.xy / uRes;
vec4 p = texture2D(tPos, uv);
vec4 v = texture2D(tVel, uv);
p.xyz += v.xyz * uDt;
if (uGravity > 0.0 && p.y < uFloor) p.y = uFloor;
gl_FragColor = p;
}
`;
const POINT_VERT = /* glsl */ `
attribute vec2 ref;
uniform sampler2D tPos, tVel, tA, cA, cB;
uniform float uMix, uStagger, uSize, uPx, uBright, uFloor, uMirror;
varying vec3 vColor;
varying float vFade;
${COMMON_GLSL}
void main() {
vec4 p = texture2D(tPos, ref);
vec4 v = texture2D(tVel, ref);
float seed = texture2D(tA, ref).w;
float prog = progressFor(uMix, uStagger, seed);
vec3 col = mix(texture2D(cA, ref).rgb, texture2D(cB, ref).rgb, prog);
col = pow(max(col, vec3(0.0)), vec3(0.8)) + 0.035;
float heat = clamp(v.w, 0.0, 1.0);
col = mix(col, vec3(0.35, 0.8, 1.6), heat * 0.55) * (1.0 + heat * 2.2);
vec3 world = p.xyz;
vFade = 1.0;
if (uMirror > 0.5) {
world.y = 2.0 * uFloor - world.y;
vFade = 0.22 * clamp(1.0 - (uFloor - world.y) * 0.45, 0.0, 1.0);
}
vColor = col * uBright * 0.16 * vFade;
vec4 mv = viewMatrix * vec4(world, 1.0);
gl_Position = projectionMatrix * mv;
gl_PointSize = max(1.0, uSize * uPx * (0.55 + 0.9 * fract(seed * 7.13)) * (1.0 + heat * 0.8) / -mv.z);
}
`;
const POINT_FRAG = /* glsl */ `
varying vec3 vColor;
varying float vFade;
void main() {
vec2 c = gl_PointCoord - 0.5;
float a = exp(-dot(c, c) * 20.0);
if (a < 0.03 || vFade <= 0.0) discard;
gl_FragColor = vec4(vColor, a);
}
`;
/** Probe the one capability the engine cannot run without. */
export function probeSupport() {
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2');
if (!gl) return { ok: false, reason: 'webgl2' };
const float = !!gl.getExtension('EXT_color_buffer_float');
const half = !!gl.getExtension('EXT_color_buffer_half_float') || float;
const lose = gl.getExtension('WEBGL_lose_context');
if (lose) lose.loseContext();
if (!half) return { ok: false, reason: 'float-targets' };
return { ok: true, float };
}
export class DissolveEngine {
/**
* @param {THREE.WebGLRenderer} renderer shared with the page's composer
* @param {number} side texture side; particle count is side * side
*/
constructor(renderer, side) {
this.renderer = renderer;
this.side = side;
this.count = side * side;
this.time = 0;
this.params = { ...DEFAULT_PARAMS };
this.mix = 0;
this.audio = { bass: 0, mid: 0 };
this.pointer = { mode: TOOL.none, strength: 0, point: new THREE.Vector3(), axis: new THREE.Vector3(0, 0, -1) };
this.waves = Array.from({ length: MAX_WAVES }, () => new THREE.Vector4(0, 0, 0, -1));
this.waveHead = 0;
this.waveStrength = 1;
this.springDip = 0;
this.floorY = -1;
const useFloat = renderer.extensions.has('EXT_color_buffer_float');
this.stateType = useFloat ? THREE.FloatType : THREE.HalfFloatType;
const makeTarget = () =>
new THREE.WebGLRenderTarget(side, side, {
type: this.stateType,
format: THREE.RGBAFormat,
minFilter: THREE.NearestFilter,
magFilter: THREE.NearestFilter,
depthBuffer: false,
stencilBuffer: false,
generateMipmaps: false,
});
this.pos = [makeTarget(), makeTarget()];
this.vel = [makeTarget(), makeTarget()];
this.flip = 0;
this.shapes = { A: null, B: null };
this.textures = {
posA: this._dataTexture(),
posB: this._dataTexture(),
colA: this._dataTexture(),
colB: this._dataTexture(),
};
this._buildSimulation();
this._buildPoints();
this._seedState();
}
_dataTexture() {
const t = new THREE.DataTexture(new Float32Array(this.count * 4), this.side, this.side, THREE.RGBAFormat, THREE.FloatType);
t.minFilter = THREE.NearestFilter;
t.magFilter = THREE.NearestFilter;
t.generateMipmaps = false;
t.needsUpdate = true;
return t;
}
_buildSimulation() {
const geometry = new THREE.BufferGeometry();
geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array([-1, -1, 0, 3, -1, 0, -1, 3, 0]), 3));
this.simCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
this.simScene = new THREE.Scene();
const res = new THREE.Vector2(this.side, this.side);
const shared = {
uRes: { value: res },
uDt: { value: 1 / 60 },
uGravity: { value: 0 },
uFloor: { value: this.floorY },
};
this.velMaterial = new THREE.ShaderMaterial({
vertexShader: FULLSCREEN_VERT,
fragmentShader: VELOCITY_FRAG,
depthTest: false,
depthWrite: false,
uniforms: {
...shared,
tPos: { value: null },
tVel: { value: null },
tA: { value: this.textures.posA },
tB: { value: this.textures.posB },
uTime: { value: 0 },
uMix: { value: 0 },
uStagger: { value: this.params.stagger },
uSpring: { value: this.params.spring },
uDamp: { value: this.params.damp },
uTurb: { value: this.params.turb },
uArc: { value: this.params.arc },
uBass: { value: 0 },
uMid: { value: 0 },
uAttr: { value: new THREE.Vector4() },
uMode: { value: 0 },
uAxis: { value: new THREE.Vector3(0, 0, -1) },
uWave: { value: this.waves },
uWaveStrength: { value: 1 },
},
});
this.posMaterial = new THREE.ShaderMaterial({
vertexShader: FULLSCREEN_VERT,
fragmentShader: POSITION_FRAG,
depthTest: false,
depthWrite: false,
uniforms: { ...shared, tPos: { value: null }, tVel: { value: null } },
});
this.simMesh = new THREE.Mesh(geometry, this.velMaterial);
this.simMesh.frustumCulled = false;
this.simScene.add(this.simMesh);
}
_buildPoints() {
const refs = new Float32Array(this.count * 2);
const positions = new Float32Array(this.count * 3);
for (let y = 0; y < this.side; y++) {
for (let x = 0; x < this.side; x++) {
const i = y * this.side + x;
refs[i * 2] = (x + 0.5) / this.side;
refs[i * 2 + 1] = (y + 0.5) / this.side;
}
}
const geometry = new THREE.BufferGeometry();
geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
geometry.setAttribute('ref', new THREE.BufferAttribute(refs, 2));
const make = (mirror) =>
new THREE.ShaderMaterial({
vertexShader: POINT_VERT,
fragmentShader: POINT_FRAG,
transparent: true,
depthWrite: false,
depthTest: false,
blending: THREE.AdditiveBlending,
uniforms: {
tPos: { value: null },
tVel: { value: null },
tA: { value: this.textures.posA },
cA: { value: this.textures.colA },
cB: { value: this.textures.colB },
uMix: { value: 0 },
uStagger: { value: this.params.stagger },
uSize: { value: 0.012 },
uPx: { value: 1000 },
uBright: { value: this.params.bright },
uFloor: { value: this.floorY },
uMirror: { value: mirror ? 1 : 0 },
},
});
this.pointMaterial = make(false);
this.mirrorMaterial = make(true);
this.points = new THREE.Points(geometry, this.pointMaterial);
this.mirror = new THREE.Points(geometry, this.mirrorMaterial);
for (const p of [this.points, this.mirror]) p.frustumCulled = false;
this.group = new THREE.Group();
this.group.add(this.mirror, this.points);
}
/** Born from a loose shell, so the first shape materialises out of a cloud. */
_seedState() {
const rng = mulberry32(1337);
const pos = new Float32Array(this.count * 4);
for (let i = 0; i < this.count; i++) {
const u = rng() * 2 - 1;
const th = rng() * Math.PI * 2;
const r = 2.2 + rng() * 2.6;
const s = Math.sqrt(1 - u * u);
pos[i * 4] = Math.cos(th) * s * r;
pos[i * 4 + 1] = u * r * 0.7;
pos[i * 4 + 2] = Math.sin(th) * s * r;
pos[i * 4 + 3] = 0;
}
const seed = new THREE.DataTexture(pos, this.side, this.side, THREE.RGBAFormat, THREE.FloatType);
seed.minFilter = THREE.NearestFilter;
seed.magFilter = THREE.NearestFilter;
seed.needsUpdate = true;
this._blit(seed, this.pos[0]);
this._blit(seed, this.pos[1]);
seed.dispose();
const zero = new THREE.DataTexture(new Float32Array(this.count * 4), this.side, this.side, THREE.RGBAFormat, THREE.FloatType);
zero.minFilter = THREE.NearestFilter;
zero.magFilter = THREE.NearestFilter;
zero.needsUpdate = true;
this._blit(zero, this.vel[0]);
this._blit(zero, this.vel[1]);
zero.dispose();
}
_blit(texture, target) {
const material = new THREE.ShaderMaterial({
vertexShader: FULLSCREEN_VERT,
fragmentShader: /* glsl */ `
uniform sampler2D tSrc;
uniform vec2 uRes;
void main() { gl_FragColor = texture2D(tSrc, gl_FragCoord.xy / uRes); }
`,
uniforms: { tSrc: { value: texture }, uRes: { value: new THREE.Vector2(this.side, this.side) } },
depthTest: false,
depthWrite: false,
});
const previous = this.simMesh.material;
this.simMesh.material = material;
this._pass(target);
this.simMesh.material = previous;
material.dispose();
}
_pass(target) {
const r = this.renderer;
const prevTarget = r.getRenderTarget();
const prevAuto = r.autoClear;
r.autoClear = false;
r.setRenderTarget(target);
r.render(this.simScene, this.simCamera);
r.setRenderTarget(prevTarget);
r.autoClear = prevAuto;
}
/**
* Upload a ShapeCloud into slot 'A' or 'B'. Both slots are Morton sorted over
* the same stage box, which is what pairs their particles spatially.
*/
setShape(slot, cloud) {
if (cloud.count !== this.count) throw new RangeError('Cloud size does not match the engine.');
const order = mortonOrder(cloud.positions, cloud.count, STAGE_MIN, STAGE_MAX);
const posTex = slot === 'A' ? this.textures.posA : this.textures.posB;
const colTex = slot === 'A' ? this.textures.colA : this.textures.colB;
const pos = posTex.image.data;
const col = colTex.image.data;
const rng = mulberry32(slot === 'A' ? 9001 : 4242);
for (let rank = 0; rank < this.count; rank++) {
const src = order[rank];
pos[rank * 4] = cloud.positions[src * 3];
pos[rank * 4 + 1] = cloud.positions[src * 3 + 1];
pos[rank * 4 + 2] = cloud.positions[src * 3 + 2];
// The seed rides in A's alpha only; the stagger reads it from there.
pos[rank * 4 + 3] = slot === 'A' ? rng() : 0;
col[rank * 4] = cloud.colors[src * 3];
col[rank * 4 + 1] = cloud.colors[src * 3 + 1];
col[rank * 4 + 2] = cloud.colors[src * 3 + 2];
col[rank * 4 + 3] = 1;
}
posTex.needsUpdate = true;
colTex.needsUpdate = true;
this.shapes[slot] = cloud;
if (slot === 'A' && !this.shapes.B) this._mirrorIntoB(posTex, colTex);
}
/** Until B is chosen, B is a copy of A so the slider never reveals an empty target. */
_mirrorIntoB() {
this.textures.posB.image.data.set(this.textures.posA.image.data);
this.textures.colB.image.data.set(this.textures.colA.image.data);
this.textures.posB.needsUpdate = true;
this.textures.colB.needsUpdate = true;
}
/** Swap which shape is A and which is B, and flip the blend to match. */
swap() {
const { posA, posB, colA, colB } = this.textures;
const seeds = new Float32Array(this.count);
const a = posA.image.data;
const b = posB.image.data;
for (let i = 0; i < this.count; i++) seeds[i] = a[i * 4 + 3];
const tmp = new Float32Array(a);
a.set(b);
b.set(tmp);
for (let i = 0; i < this.count; i++) {
a[i * 4 + 3] = seeds[i];
b[i * 4 + 3] = 0;
}
const tc = new Float32Array(colA.image.data);
colA.image.data.set(colB.image.data);
colB.image.data.set(tc);
for (const t of [posA, posB, colA, colB]) t.needsUpdate = true;
[this.shapes.A, this.shapes.B] = [this.shapes.B, this.shapes.A];
this.mix = 1 - this.mix;
}
setMix(v) {
this.mix = Math.min(1, Math.max(0, v));
}
setParam(name, value) {
this.params[name] = value;
}
/** Fire a shockwave from a world point. */
shockwave(point, strength = 1) {
this.waves[this.waveHead].set(point.x, point.y, point.z, this.time);
this.waveHead = (this.waveHead + 1) % MAX_WAVES;
this.waveStrength = strength;
this.springDip = 0.35;
}
/** Advance the simulation by `dt` seconds (clamped for stability). */
step(dt) {
const d = Math.min(dt, 1 / 30);
this.time += d;
this.springDip = Math.max(0, this.springDip - d);
const v = this.velMaterial.uniforms;
const dip = this.springDip > 0 ? 0.25 : 1;
const collapsed = this.params.gravity > 0;
v.uDt.value = d;
v.uTime.value = this.time;
v.uMix.value = this.mix;
v.uStagger.value = this.params.stagger;
v.uSpring.value = collapsed ? 0 : this.params.spring * dip;
v.uDamp.value = collapsed ? 0.35 : this.params.damp;
v.uTurb.value = this.params.turb;
v.uArc.value = this.params.arc;
v.uGravity.value = this.params.gravity;
v.uBass.value = this.audio.bass;
v.uMid.value = this.audio.mid;
v.uMode.value = this.pointer.mode;
v.uAttr.value.set(this.pointer.point.x, this.pointer.point.y, this.pointer.point.z, this.pointer.strength);
v.uAxis.value.copy(this.pointer.axis);
v.uWaveStrength.value = this.waveStrength;
const p = this.posMaterial.uniforms;
p.uDt.value = d;
p.uGravity.value = this.params.gravity;
const read = this.flip;
const write = 1 - this.flip;
v.tPos.value = this.pos[read].texture;
v.tVel.value = this.vel[read].texture;
this.simMesh.material = this.velMaterial;
this._pass(this.vel[write]);
p.tPos.value = this.pos[read].texture;
p.tVel.value = this.vel[write].texture;
this.simMesh.material = this.posMaterial;
this._pass(this.pos[write]);
this.flip = write;
for (const m of [this.pointMaterial, this.mirrorMaterial]) {
m.uniforms.tPos.value = this.pos[this.flip].texture;
m.uniforms.tVel.value = this.vel[this.flip].texture;
m.uniforms.uMix.value = this.mix;
m.uniforms.uStagger.value = this.params.stagger;
m.uniforms.uBright.value = this.params.bright;
}
}
/** Point size in world units, plus the pixel scale for the current viewport. */
setView(drawingBufferHeight, fovDegrees) {
const px = drawingBufferHeight / (2 * Math.tan((fovDegrees * Math.PI) / 360));
for (const m of [this.pointMaterial, this.mirrorMaterial]) {
m.uniforms.uPx.value = px;
m.uniforms.uSize.value = 0.012 * this.params.size * (this.side >= 1024 ? 0.55 : this.side >= 512 ? 0.7 : 1.0);
}
}
dispose() {
for (const t of [...this.pos, ...this.vel]) t.dispose();
for (const t of Object.values(this.textures)) t.dispose();
this.points.geometry.dispose();
for (const m of [this.velMaterial, this.posMaterial, this.pointMaterial, this.mirrorMaterial]) m.dispose();
this.simMesh.geometry.dispose();
}
}