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
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { PLACES, SPAWN, CAMPUS_RADIUS, PLACE_TRIGGER, DESK_OBJECTS, placeById, nearestInteractable, standPointFor, dist2 } from '../src/desktop/world/places.js';
import {
AGENT_TRIGGER,
APPROACH_DISTANCE,
GREET_RANGE,
arrivalMessage,
castSpots,
embedSnippet,
groundingPrompt,
isCastable,
nearestAgent,
parseSse,
pickCast,
pickGreeter,
toCastMember,
} from '../src/desktop/world/cast.js';
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const agent = (o = {}) => ({
id: '11111111-1111-4111-8111-111111111111',
name: 'AxisXV',
description: 'Evidence-first Signal Cards for tokens, wallets, repos, projects, and AI agents.',
skills: ['greet', 'quick-signal-card'],
avatar_thumbnail: 'https://cdn.example/thumb/a.png',
avatar_model_url: 'https://cdn.example/u/a.glb',
home_url: '/agents/11111111-1111-4111-8111-111111111111',
chat_count: 90,
is_registered: false,
onchain: null,
...o,
});
describe('cast selection', () => {
it('keeps only agents with a real name and a public body', () => {
expect(isCastable(agent())).toBe(true);
expect(isCastable(agent({ avatar_model_url: null }))).toBe(false);
expect(isCastable(agent({ name: '' }))).toBe(false);
expect(isCastable(agent({ name: 'Avatar #e6f105' }))).toBe(false);
expect(isCastable(agent({ name: 'model (11)' }))).toBe(false);
expect(isCastable(agent({ name: 'x'.repeat(41) }))).toBe(false);
expect(isCastable(agent({ name: 'Agent Ada' }))).toBe(true);
expect(isCastable(null)).toBe(false);
});
it('rejects every onboarding placeholder name the server also hides, case-insensitively', () => {
const src = readFileSync(resolve(root, 'api/agents/public.js'), 'utf8');
const list = src.match(/const PLACEHOLDER_NAMES = \[([^\]]+)\]/)[1].match(/'([^']+)'/g).map((s) => s.slice(1, -1));
expect(list.length).toBeGreaterThan(3);
for (const name of list) {
expect(isCastable(agent({ name })), name).toBe(false);
expect(isCastable(agent({ name: name.toUpperCase() })), name).toBe(false);
}
});
it('maps a public agent record to a cast member with only the fields the world needs', () => {
const m = toCastMember(agent({ onchain: { network: 'mainnet', asset: 'THREEsynthetic1111' }, is_registered: true }));
expect(m).toMatchObject({ id: agent().id, name: 'AxisXV', glb: 'https://cdn.example/u/a.glb', chats: 90, registered: true, home: '/agents/11111111-1111-4111-8111-111111111111' });
expect(m.description).toMatch(/Signal Cards/);
expect(m.skills).toEqual(['greet', 'quick-signal-card']);
expect(m.thumb).toBe('https://cdn.example/thumb/a.png');
expect(toCastMember(agent({ description: ' ', skills: null, home_url: null })).description).toBe('');
expect(toCastMember(agent({ home_url: null })).home).toBe(`/agents/${agent().id}`);
// The onboarding bio says nothing about the agent, so it counts as no description.
expect(toCastMember(agent({ description: 'A friendly starter agent. Edit the personality to make it yours.' })).description).toBe('');
});
it('picks the most talked-to real agents, prefers distinct bodies, and caps the cast', () => {
const list = [
agent({ id: 'a', name: 'One', chat_count: 5, avatar_model_url: 'https://x/1.glb' }),
agent({ id: 'b', name: 'Two', chat_count: 50, avatar_model_url: 'https://x/2.glb' }),
agent({ id: 'c', name: 'My First Agent', chat_count: 500 }),
agent({ id: 'd', name: 'Three', chat_count: 20, avatar_model_url: null }),
agent({ id: 'e', name: 'Four', chat_count: 40, avatar_model_url: 'https://x/2.glb' }),
agent({ id: 'f', name: 'Five', chat_count: 1, avatar_model_url: 'https://x/5.glb' }),
];
const cast = pickCast(list, { max: 3 });
expect(cast.map((m) => m.id)).toEqual(['b', 'a', 'f']);
expect(pickCast(list, { max: 10 }).map((m) => m.id)).toEqual(['b', 'a', 'f', 'e']);
expect(pickCast([], { max: 3 })).toEqual([]);
expect(pickCast(null, { max: 3 })).toEqual([]);
});
it('names the greeter: the most talked-to member who has something to say about itself', () => {
const cast = pickCast([
agent({ id: 'a', name: 'Quiet', chat_count: 900, description: '' }),
agent({ id: 'b', name: 'Host', chat_count: 30 }),
agent({ id: 'c', name: 'Also', chat_count: 10 }),
], { max: 5 });
expect(pickGreeter(cast)?.id).toBe('b');
expect(pickGreeter([toCastMember(agent({ description: null }))])?.id).toBe(agent().id);
expect(pickGreeter([])).toBeNull();
});
});
describe('cast placement', () => {
it('puts the greeter on the gate path and everybody else at a distinct, deterministic spot', () => {
const spots = castSpots(9, PLACES);
expect(spots).toHaveLength(9);
expect(castSpots(9, PLACES)).toEqual(spots);
const seen = new Set(spots.map((s) => `${s.x.toFixed(2)},${s.z.toFixed(2)}`));
expect(seen.size).toBe(9);
// Greeter: beside the path between the gate and the desk, within sight of the spawn.
expect(spots[0].role).toBe('greeter');
expect(Math.sqrt(dist2(spots[0].x, spots[0].z, SPAWN.x, SPAWN.z))).toBeLessThan(GREET_RANGE * 2);
expect(Math.abs(spots[0].x)).toBeGreaterThan(1.2);
for (const s of spots) {
expect(Number.isFinite(s.yaw)).toBe(true);
expect(Math.hypot(s.x, s.z)).toBeLessThan(CAMPUS_RADIUS - 2);
// Never inside a building's keep-out, and never on the desk.
for (const p of PLACES) expect(Math.sqrt(dist2(s.x, s.z, p.x, p.z)), `${s.role} vs ${p.id}`).toBeGreaterThan(p.keepout + 0.9);
const office = placeById('office');
expect(Math.sqrt(dist2(s.x, s.z, office.x, office.z))).toBeGreaterThan(3);
}
// Most of the cast gathers at Agent Plaza.
const plaza = placeById('agents');
expect(spots.filter((s) => Math.sqrt(dist2(s.x, s.z, plaza.x, plaza.z)) < plaza.keepout + 4).length).toBeGreaterThanOrEqual(3);
});
it('runs out of spots gracefully and asks for none', () => {
expect(castSpots(0, PLACES)).toEqual([]);
expect(castSpots(40, PLACES).length).toBeGreaterThanOrEqual(12);
});
it('finds the agent in reach and names the prompt after them', () => {
const agents = [
{ id: 'a', name: 'AxisXV', sub: 'Signal cards', x: 0, z: 0 },
{ id: 'b', name: 'Vera', sub: 'Concierge', x: 1.5, z: 0 },
];
expect(nearestAgent(1.2, 0, agents)).toMatchObject({ type: 'agent', id: 'b', title: 'Talk to Vera', x: 1.5, z: 0 });
expect(nearestAgent(-1, 0, agents)).toMatchObject({ id: 'a', sub: 'Signal cards' });
expect(nearestAgent(0, AGENT_TRIGGER + 0.1, [agents[0]])).toBeNull();
expect(nearestAgent(0, 0, [])).toBeNull();
// Tapping an agent walks the visitor to within talking range.
expect(APPROACH_DISTANCE).toBeLessThan(AGENT_TRIGGER);
expect(APPROACH_DISTANCE).toBeGreaterThan(1);
});
it('lets an agent take the prompt from a place when they are closer, but never from the desk', () => {
const ex = placeById('exchange');
const s = standPointFor(ex);
const agents = [{ id: 'a', name: 'AxisXV', sub: '', x: s.x + 1, z: s.z }];
expect(nearestInteractable(s.x, s.z, { agents })).toMatchObject({ type: 'agent', id: 'a' });
expect(nearestInteractable(s.x, s.z)).toMatchObject({ type: 'place', id: 'exchange' });
const office = placeById('office');
const monitor = DESK_OBJECTS.find((o) => o.id === 'monitor');
const px = office.x + monitor.dx;
const pz = office.z + monitor.dz + 0.5;
expect(nearestInteractable(px, pz, { agents: [{ id: 'a', name: 'A', sub: '', x: px + 0.2, z: pz }] })).toMatchObject({ type: 'object', id: 'monitor' });
// A place well inside its trigger still wins over an agent out of reach.
expect(nearestInteractable(s.x, s.z, { agents: [{ id: 'a', name: 'A', sub: '', x: s.x + AGENT_TRIGGER + PLACE_TRIGGER, z: s.z }] })).toMatchObject({ type: 'place' });
});
});
describe('talking', () => {
it('splits SSE frames and keeps the unfinished tail', () => {
const r = parseSse('data: {"type":"chunk","text":"Hey"}\n\ndata: {"type":"chunk","text":" there"}\n\ndata: {"type":"do');
expect(r.events).toEqual([{ type: 'chunk', text: 'Hey' }, { type: 'chunk', text: ' there' }]);
expect(r.rest).toBe('data: {"type":"do');
const r2 = parseSse(r.rest + 'ne","reply":"Hey there"}\n\n: comment\n\nevent: x\ndata: not json\n\n');
expect(r2.events).toEqual([{ type: 'done', reply: 'Hey there' }]);
expect(r2.rest).toBe('');
expect(parseSse('')).toEqual({ events: [], rest: '' });
});
it('writes the one-tag embed for a specific agent against the pinned library build', () => {
const m = toCastMember(agent());
const snip = embedSnippet(m);
expect(snip).toContain('<script type="module" src="https://three.ws/agent-3d/');
expect(snip).toContain(`<agent-3d agent-id="${m.id}"`);
expect(snip).not.toMatch(/\u2014|\u2013/);
});
it('grounds an agent in its own public record and nothing invented', () => {
const m = toCastMember(agent());
const p = groundingPrompt(m, { place: 'Agent Plaza' });
expect(p).toContain('AxisXV');
expect(p).toContain(m.description);
expect(p).toContain('quick-signal-card');
expect(p).toContain('Agent Plaza');
expect(p).toContain('$THREE');
expect(p.length).toBeLessThanOrEqual(2000);
const long = groundingPrompt(toCastMember(agent({ description: 'x'.repeat(5000), skills: Array.from({ length: 80 }, (_, i) => `skill-${i}`) })), {});
expect(long.length).toBeLessThanOrEqual(2000);
expect(groundingPrompt(toCastMember(agent({ description: '', skills: [] })), {})).not.toMatch(/undefined|null/);
});
it('asks the greeter for a spoken welcome that points at the desk', () => {
const msg = arrivalMessage('Nir');
expect(msg).toMatch(/Nir/);
expect(msg).toMatch(/desk/i);
expect(arrivalMessage('')).not.toMatch(/undefined/);
expect(arrivalMessage('')).not.toMatch(/\u2014|\u2013/);
});
});