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
// End-to-end conformance run for the /play event souvenir drop.
//
// Proves the four properties the feature promises, against a real browser, a
// real Colyseus server and a real persistence round-trip:
//
// 1. LIVE WINDOW → the souvenir is granted on join, announced once, equips,
// and shows on the avatar and in the wardrobe.
// 2. IDEMPOTENT → a full reconnect as the same account re-grants nothing:
// no second announcement, no duplicate in the owned list, and the item is
// still worn (it persisted).
// 3. VISIBLE TO PEERS → a second player in the world sees the wearer's
// loadout on the shared schema, which is what makes a souvenir social.
// 4. CLOSED WINDOW → a fresh account joining after the event ends is granted
// nothing, while an account that earned it earlier still wears it.
//
// The event config is served from THIS process (a throwaway static endpoint) so
// nothing in the repo is edited to fake a live window, and the window can be
// opened and closed between phases of one run. Point the game server at it with
// EVENT_CONFIG_URL, see below.
//
// Both servers run on PRIVATE ports, and the browser is pointed at the game
// server with window.GAME_SERVER_URL. This machine routinely has several agents'
// Vite instances and load tests running at once, and an earlier run on the
// conventional :3000/:2567 pair ended up sharing its world with another job's
// synthetic clients: hundreds of unrelated joins, seat reservations expiring,
// and no trustworthy read on anything.
//
// node scripts/play-souvenir-e2e.mjs # boots both servers itself
// EXTERNAL=1 node scripts/play-souvenir-e2e.mjs # you started them yourself
//
// Exit code is 0 only when every check passes.
import { chromium } from 'playwright';
import { createServer } from 'node:http';
import { spawn } from 'node:child_process';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
// Private ports by default, so a neighbouring agent's dev server or load test
// can neither serve this run's pages nor join this run's world.
const VITE_PORT = Number(process.env.VITE_PORT || 3111);
const MP_PORT = Number(process.env.MP_PORT || 2571);
const BASE = (process.env.BASE || `http://localhost:${VITE_PORT}`).replace(/\/$/, '');
const GAME_SERVER = process.env.GAME_SERVER || `ws://127.0.0.1:${MP_PORT}`;
const MINT = process.env.COIN || 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const WORLD = `${BASE}/play?coin=${encodeURIComponent(MINT)}&name=three.ws&symbol=three`;
const SOUVENIR_ID = 'laurel-meetup';
const CONFIG_PORT = Number(process.env.CONFIG_PORT || 4599);
const EXTERNAL = process.env.EXTERNAL === '1';
const LOAD_MS = Number(process.env.LOAD_MS || 300_000);
const JOIN_MS = Number(process.env.JOIN_MS || 180_000);
const t0 = Date.now();
const at = () => `+${((Date.now() - t0) / 1000).toFixed(1)}s`;
const results = [];
function check(name, ok, detail = '') {
results.push({ name, ok, detail });
console.log(`${at()} ${ok ? 'PASS' : 'FAIL'} ${name}${detail ? `: ${detail}` : ''}`);
return ok;
}
// ── the event config this run controls ─────────────────────────────────────
// `live` flips the window between "happening right now" and "ended an hour ago"
// without touching public/event.json. The game server re-reads on its own TTL,
// so a phase change is a matter of flipping this and waiting out the cache.
let windowState = 'live';
function configDoc() {
const now = Date.now();
const [startsAt, endsAt] = windowState === 'live'
? [now - 10 * 60_000, now + 60 * 60_000]
: [now - 3 * 60 * 60_000, now - 60 * 60_000];
return {
id: 'souvenir-e2e',
name: '$THREE Community Day 2026',
tagline: 'Conformance run for the souvenir drop.',
startsAt: new Date(startsAt).toISOString(),
endsAt: new Date(endsAt).toISOString(),
link: `/play?coin=${MINT}&name=three.ws&symbol=three`,
souvenir: { cosmeticId: SOUVENIR_ID },
agenda: [],
};
}
function serveConfig() {
const server = createServer((req, res) => {
res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
res.end(JSON.stringify(configDoc()));
});
return new Promise((r) => server.listen(CONFIG_PORT, '127.0.0.1', () => r(server)));
}
// ── servers ────────────────────────────────────────────────────────────────
const procs = [];
function start(name, cmd, args, { cwd = ROOT, env = {} } = {}) {
const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env }, stdio: ['ignore', 'pipe', 'pipe'] });
procs.push(child);
for (const stream of [child.stdout, child.stderr]) {
stream.setEncoding('utf8');
stream.on('data', (c) => {
for (const line of c.split('\n')) {
// Only surface what this run is about; a Colyseus log line per join
// would bury the checks.
if (line && /souvenir|event-drop|error|Error|listening|ready in/i.test(line)) {
console.log(`${at()} [${name}] ${line.trim().slice(0, 200)}`);
}
}
});
}
return child;
}
async function waitFor(url, timeoutMs) {
const deadline = Date.now() + timeoutMs;
for (;;) {
try {
const res = await fetch(url);
if (res.ok || res.status === 404) return true;
} catch { /* not up yet */ }
if (Date.now() > deadline) return false;
await new Promise((r) => setTimeout(r, 1000));
}
}
// ── browser helpers ────────────────────────────────────────────────────────
async function until(page, fn, { timeout = 30_000, every = 300, arg } = {}) {
const deadline = Date.now() + timeout;
let last;
for (;;) {
try { last = await page.evaluate(fn, arg); } catch (err) { last = { evalError: String(err).slice(0, 140) }; }
if (last === true || last?.ok === true) return last;
if (Date.now() > deadline) return last;
await page.waitForTimeout(every);
}
}
async function dismissOverlays(page, rounds = 6) {
for (let i = 0; i < rounds; i++) {
const clicked = await page.evaluate(() => {
const btn = [...document.querySelectorAll('button')].find(
(b) => /^(continue|enter the world|got it|start|close|skip|drop in now)$/i.test(b.textContent.trim()) && b.offsetParent,
);
if (btn) { btn.click(); return btn.textContent.trim(); }
return null;
});
if (!clicked) break;
await page.waitForTimeout(500);
}
}
// A browser context is one player: its own storage means its own guest id, which
// is the identity the souvenir is granted against.
async function openPlayer(browser, tag, storageState) {
const ctx = await browser.newContext(storageState ? { storageState } : {});
const page = await ctx.newPage();
const consoleErrors = [];
page.on('console', (m) => {
if (m.type() !== 'error') return;
const text = m.text();
// A dev origin logs unrelated noise (source maps, favicon, HMR); only the
// page's own failures matter here.
if (/favicon|sourcemap|Failed to load resource/i.test(text)) return;
consoleErrors.push(text.slice(0, 200));
});
page.on('pageerror', (e) => consoleErrors.push(`pageerror: ${String(e.message).slice(0, 200)}`));
// Record every souvenir announcement this client receives, so "exactly once"
// is measurable rather than assumed. Installed before any app code runs.
// The same script pins the game server to this run's private instance
// (src/shared/game-server-url.js checks window.GAME_SERVER_URL first).
await page.addInitScript((gameServer) => {
window.GAME_SERVER_URL = gameServer;
window.__SOUVENIRS__ = [];
const tick = setInterval(() => {
const net = window.__CC__?.net;
if (!net || net.__souvenirTap) return;
net.__souvenirTap = true;
try { net.on('souvenir', (m) => window.__SOUVENIRS__.push(m)); } catch { /* older build */ }
clearInterval(tick);
}, 200);
}, GAME_SERVER);
// A /play page is a WebGL scene under software rasterisation, and this repo is
// worked on by several agents at once: a neighbouring test suite can take the
// box to zero free memory and Chromium answers with "Page crashed" rather than
// a load error. Retry rather than reporting a machine-state failure as a
// feature failure.
let loaded = false;
for (let attempt = 1; attempt <= 3 && !loaded; attempt++) {
try {
await page.goto(WORLD, { waitUntil: 'domcontentloaded', timeout: LOAD_MS });
loaded = true;
} catch (err) {
console.log(`${at()} [${tag}] load attempt ${attempt} failed: ${String(err.message).split('\n')[0]}`);
if (attempt === 3) throw err;
await new Promise((r) => setTimeout(r, 10_000));
}
}
await dismissOverlays(page);
const joined = await until(page, () => {
const net = window.__CC__?.net;
return { ok: net?.status === 'online' && window.__CC__?.phase === 'world', status: net?.status, phase: window.__CC__?.phase };
}, { timeout: JOIN_MS });
if (joined?.ok !== true) throw new Error(`[${tag}] never joined the world: ${JSON.stringify(joined)}`);
console.log(`${at()} [${tag}] in the world`);
return { tag, ctx, page, consoleErrors };
}
// The client's own view of what it owns and wears, straight off the live scene.
const cosmeticsState = () => {
const cc = window.__CC__;
const snap = cc?._cosmeticsSnap?.cosmetics || {};
return {
owned: [...(snap.owned || [])],
equipped: { ...(snap.equipped || {}) },
wire: cc?.net?.state?.players?.get?.(cc.net.sessionId)?.cosmetics ?? null,
souvenirs: window.__SOUVENIRS__ || [],
cardVisible: !!document.querySelector('.es-card'),
cardName: document.querySelector('.es-card .es-name')?.textContent || '',
};
};
async function main() {
const configServer = await serveConfig();
console.log(`${at()} event config served at http://127.0.0.1:${CONFIG_PORT}/event.json (window: ${windowState})`);
if (!EXTERNAL) {
start('vite', 'npx', ['vite', '--port', String(VITE_PORT), '--strictPort']);
// The game server reads the event config from THIS process, not from
// three.ws, which is what lets the run open and close the window at will.
start('colyseus', 'node', ['src/index.js'], {
cwd: resolve(ROOT, 'multiplayer'),
env: {
PORT: String(MP_PORT),
EVENT_CONFIG_URL: `http://127.0.0.1:${CONFIG_PORT}/event.json`,
// Re-read the window quickly so the closed-window phase does not cost
// two minutes of wall clock.
EVENT_CONFIG_TTL_MS: String(process.env.EVENT_CONFIG_TTL_MS || 10_000),
// The server's default origin allowlist is localhost:3000-3003, and
// this run deliberately sits outside that range to stay clear of other
// agents' dev servers. Without this the socket is refused and the page
// sits on "loading" forever, which reads exactly like a broken feature.
ALLOWED_ORIGINS: `${BASE},http://127.0.0.1:${VITE_PORT}`,
},
});
if (!await waitFor(`http://127.0.0.1:${MP_PORT}/health`, 90_000)) throw new Error('colyseus never came up');
if (!await waitFor(BASE, 120_000)) throw new Error('vite never came up');
console.log(`${at()} servers up: vite :${VITE_PORT}, colyseus :${MP_PORT}`);
}
// Memory-frugal flags: /dev/shm in this container is far smaller than
// Chromium assumes, and a shared box means the renderer must not be greedy.
const browser = await chromium.launch({
args: [
'--disable-dev-shm-usage',
'--disable-extensions',
'--disable-background-timer-throttling',
'--js-flags=--max-old-space-size=768',
],
});
const players = [];
try {
// ── Phase 1: window LIVE ───────────────────────────────────────────────
const alice = await openPlayer(browser, 'alice');
players.push(alice);
const granted = await until(alice.page, () => {
const s = window.__SOUVENIRS__ || [];
return { ok: s.length > 0, n: s.length };
}, { timeout: 60_000 });
check('live window: souvenir announced on join', granted?.ok === true, JSON.stringify(granted));
const afterGrant = await alice.page.evaluate(cosmeticsState);
check('live window: announcement names the item', afterGrant.souvenirs[0]?.id === SOUVENIR_ID,
JSON.stringify(afterGrant.souvenirs[0] || null));
check('live window: owned exactly once', afterGrant.owned.filter((i) => i === SOUVENIR_ID).length === 1,
`owned=${JSON.stringify(afterGrant.owned)}`);
check('live window: drop card is on screen', afterGrant.cardVisible, afterGrant.cardName);
// Wear it from the card, exactly as a player would.
await alice.page.click('.es-card .es-btn-primary');
const worn = await until(alice.page, ([id]) => {
const eq = window.__CC__?._cosmeticsSnap?.cosmetics?.equipped || {};
return { ok: eq.headwear === id, equipped: eq };
}, { timeout: 30_000, arg: [SOUVENIR_ID] });
check('live window: "Wear it" equips the souvenir', worn?.ok === true, JSON.stringify(worn?.equipped || worn));
const onWire = await until(alice.page, ([id]) => {
const cc = window.__CC__;
const wire = cc?.net?.state?.players?.get?.(cc.net.sessionId)?.cosmetics || '';
return { ok: wire.split(',').includes(id), wire };
}, { timeout: 30_000, arg: [SOUVENIR_ID] });
check('live window: souvenir published on the shared schema', onWire?.ok === true, JSON.stringify(onWire));
// A peer must actually see it, that is what a souvenir is for.
const bob = await openPlayer(browser, 'bob');
players.push(bob);
// `_cosWire` is the loadout string the peer's RemotePlayer last rendered, so
// this asserts the souvenir actually reached another client's rig, not just
// that the schema carried it.
const peerSees = await until(bob.page, ([id]) => {
const remotes = [...(window.__CC__?.remotes || new Map())].map(([, r]) => r);
const wires = remotes.map((r) => String(r._cosWire || ''));
return { ok: wires.some((w) => w.split(',').includes(id)), n: remotes.length, wires };
}, { timeout: 60_000, arg: [SOUVENIR_ID] });
check('live window: another player sees the souvenir worn', peerSees?.ok === true, JSON.stringify(peerSees));
// The wardrobe is the other half of the moment.
await alice.page.evaluate(() => window.__CC__._toggleWardrobe());
const inWardrobe = await until(alice.page, ([id]) => {
const card = document.querySelector(`.cw-card[data-id="${id}"]`);
if (!card) return { ok: false, reason: 'no card' };
return {
ok: !card.classList.contains('cw-locked'),
tier: card.getAttribute('data-tier'),
label: card.querySelector('.cw-price')?.textContent || '',
equipped: card.classList.contains('cw-equipped'),
};
}, { timeout: 30_000, arg: [SOUVENIR_ID] });
check('live window: wardrobe shows it owned, event-tier and equipped',
inWardrobe?.ok === true && inWardrobe.tier === 'event' && inWardrobe.equipped === true,
JSON.stringify(inWardrobe));
await alice.page.evaluate(() => window.__CC__._wardrobe?.close());
// ── Phase 2: reconnect as the SAME account ─────────────────────────────
const aliceState = await alice.ctx.storageState();
await alice.page.close();
await alice.ctx.close();
players.pop();
const aliceAgain = await openPlayer(browser, 'alice-rejoin', aliceState);
players.push(aliceAgain);
// Give the server the same amount of time it took to announce the first
// time; a duplicate would have landed well inside it.
await aliceAgain.page.waitForTimeout(15_000);
const rejoin = await aliceAgain.page.evaluate(cosmeticsState);
check('rejoin: no second announcement', rejoin.souvenirs.length === 0,
`announcements=${rejoin.souvenirs.length}`);
check('rejoin: still owned exactly once', rejoin.owned.filter((i) => i === SOUVENIR_ID).length === 1,
`owned=${JSON.stringify(rejoin.owned)}`);
check('rejoin: still worn (persisted across the reconnect)', rejoin.equipped.headwear === SOUVENIR_ID,
JSON.stringify(rejoin.equipped));
check('rejoin: no drop card (nothing new happened)', rejoin.cardVisible === false);
// ── Phase 3: window CLOSED ─────────────────────────────────────────────
windowState = 'ended';
// The server was started with a short EVENT_CONFIG_TTL_MS, so waiting a
// little past it is enough for the next join to read the closed window
// rather than the cached live one.
const ttlWait = Number(process.env.EVENT_CONFIG_TTL_MS || 10_000) + 5_000;
console.log(`${at()} event window flipped to ENDED; waiting ${Math.round(ttlWait / 1000)}s for the server's config TTL`);
await new Promise((r) => setTimeout(r, ttlWait));
const carol = await openPlayer(browser, 'carol-after');
players.push(carol);
await carol.page.waitForTimeout(15_000);
const after = await carol.page.evaluate(cosmeticsState);
check('closed window: a new player is granted nothing', after.souvenirs.length === 0 && !after.owned.includes(SOUVENIR_ID),
`announcements=${after.souvenirs.length} owned=${JSON.stringify(after.owned)}`);
check('closed window: no drop card', after.cardVisible === false);
const aliceStill = await aliceAgain.page.evaluate(cosmeticsState);
check('closed window: an earlier attendee still owns and wears it',
aliceStill.owned.includes(SOUVENIR_ID) && aliceStill.equipped.headwear === SOUVENIR_ID,
JSON.stringify({ owned: aliceStill.owned, equipped: aliceStill.equipped }));
// Someone who missed it sees the item, learns it was earned live, and is
// offered no way to buy it.
await carol.page.evaluate(() => window.__CC__._toggleWardrobe());
const lockedCard = await until(carol.page, ([id]) => {
const card = document.querySelector(`.cw-card[data-id="${id}"]`);
if (!card) return { ok: false, reason: 'no card' };
return { ok: true, locked: card.classList.contains('cw-locked'), label: card.querySelector('.cw-price')?.textContent || '' };
}, { timeout: 30_000, arg: [SOUVENIR_ID] });
check('closed window: wardrobe shows it locked and not for sale',
lockedCard?.locked === true && /not for sale/i.test(lockedCard.label || ''),
JSON.stringify(lockedCard));
// ── console hygiene ────────────────────────────────────────────────────
for (const p of players) {
check(`${p.tag}: no console errors`, p.consoleErrors.length === 0, p.consoleErrors.slice(0, 3).join(' | '));
}
} finally {
await browser.close().catch(() => {});
configServer.close();
for (const c of procs) { try { c.kill('SIGTERM'); } catch { /* already gone */ } }
}
const failed = results.filter((r) => !r.ok);
console.log(`\n${at()} ${results.length - failed.length}/${results.length} checks passed`);
if (failed.length) {
for (const f of failed) console.log(` FAIL ${f.name}: ${f.detail}`);
process.exit(1);
}
}
main().catch((err) => {
console.error(err);
for (const c of procs) { try { c.kill('SIGTERM'); } catch { /* already gone */ } }
process.exit(1);
});