Skip to content

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.

12.9 KB
Raw Blame
// Souvenir drop conformance run: real Colyseus server, real rooms, real
// persistence, no browser.
//
// The browser run ([play-souvenir-e2e.mjs](play-souvenir-e2e.mjs)) is the one
// that proves the UI. This one proves the CONTRACT, and it does so with the
// actual colyseus.js client joining the actual `walk_world` room, so every
// assertion below crosses the real wire:
//
//   1. LIVE WINDOW     a player joining the event world is granted the souvenir,
//                      announced exactly once, and can equip it.
//   2. IDEMPOTENT      the same account rejoining is granted nothing more, gets
//                      no second announcement, and is still wearing it (proving
//                      the grant persisted, not just stuck in room memory).
//   3. WRONG WORLD     the same account, same instant, in a different coin world
//                      is granted nothing.
//   4. PEER-VISIBLE    a second player in the room sees the wearer's loadout on
//                      the shared schema.
//   5. CLOSED WINDOW   after the window ends, a fresh account gets nothing while
//                      the earlier attendee still owns and wears it.
//
// It boots its own game server on a private port against an event config it
// serves itself, so it edits nothing in the repo and leaves no live window
// behind. It needs no Vite, no GPU and no display, which is what lets it run on
// a machine too loaded to hold a WebGL page open.
//
//   node scripts/play-souvenir-conformance.mjs                         # the laurel
//   node scripts/play-souvenir-conformance.mjs star-shades-meetup-2    # any event souvenir
//
// Exit code is 0 only when every check passes.

import { Client } from 'colyseus.js';
import { createServer } from 'node:http';
import { spawn } from 'node:child_process';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { getCosmetic } from '../multiplayer/src/cosmetics-catalog.js';

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const MP_PORT = Number(process.env.MP_PORT || 2572);
const CONFIG_PORT = Number(process.env.CONFIG_PORT || 4601);
const ENDPOINT = `ws://127.0.0.1:${MP_PORT}`;
const MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const OTHER_MINT = 'THREEsynthetic1111111111111111111111111111';
const SOUVENIR_ID = process.argv[2] || 'laurel-meetup';
// The wardrobe slot the souvenir equips into, read from the catalog so a
// headwear laurel and eyewear shades are held to the same contract.
const SLOT = getCosmetic(SOUVENIR_ID)?.slot;
if (getCosmetic(SOUVENIR_ID)?.tier !== 'event') {
	console.error(`${SOUVENIR_ID} is not an event-tier cosmetic in multiplayer/src/cosmetics-catalog.js`);
	process.exit(1);
}
const TTL_MS = 4000;

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;
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// ── the event config this run controls ─────────────────────────────────────

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-conformance',
		name: '$THREE Community Day 2026',
		startsAt: new Date(startsAt).toISOString(),
		endsAt: new Date(endsAt).toISOString(),
		link: `/play?coin=${MINT}&name=three.ws&symbol=three`,
		souvenir: { cosmeticId: SOUVENIR_ID },
		agenda: [],
	};
}

// ── the game server ────────────────────────────────────────────────────────

const procs = [];
function startServer() {
	const child = spawn('node', ['src/index.js'], {
		cwd: resolve(ROOT, 'multiplayer'),
		env: {
			...process.env,
			PORT: String(MP_PORT),
			EVENT_CONFIG_URL: `http://127.0.0.1:${CONFIG_PORT}/event.json`,
			EVENT_CONFIG_TTL_MS: String(TTL_MS),
		},
		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')) {
				if (line && /souvenir|event-drop|EADDRINUSE|failed to start/i.test(line)) {
					console.log(`${at()} [server] ${line.trim().slice(0, 160)}`);
				}
			}
		});
	}
	return child;
}

async function waitForHealth(timeoutMs) {
	const deadline = Date.now() + timeoutMs;
	for (;;) {
		try {
			if ((await fetch(`http://127.0.0.1:${MP_PORT}/health`)).ok) return true;
		} catch { /* not up yet */ }
		if (Date.now() > deadline) return false;
		await sleep(500);
	}
}

// ── a player ───────────────────────────────────────────────────────────────

// One player = one guest token, which is the identity the souvenir is granted
// against. Reusing a token across joins is exactly what a browser reconnect
// does, so `guestToken` is what makes the idempotency check meaningful.
async function join({ coin = MINT, guestToken = '', name = 'QA' } = {}) {
	const client = new Client(ENDPOINT);
	const souvenirs = [];
	let profile = null;
	let token = guestToken;

	const room = await client.joinOrCreate('walk_world', {
		token: coin,
		coin,
		coinName: coin === MINT ? 'three.ws' : 'Synthetic',
		coinSymbol: coin === MINT ? 'three' : 'syn',
		name,
		guestToken,
	});
	room.onMessage('souvenir', (m) => souvenirs.push(m));
	room.onMessage('profile', (m) => { profile = m; });
	room.onMessage('guestToken', (m) => { if (m?.token) token = m.token; });
	// A real world pushes a steady stream of minigame, quest and HUD traffic that
	// this run has no opinion about. colyseus.js warns once per unhandled type,
	// which drowns the checks; absorb the lot with a wildcard handler.
	room.onMessage('*', () => {});
	// Handlers are attached, so say so the way the real client does
	// (src/game/community-net.js). The server holds the join snapshot (profile,
	// guest token) until this arrives, falling back only after JOIN_SETTLE_MS.
	room.send('ready');

	// Let the join handshake finish: the profile echo and any grant both land in
	// the first moments after the room resolves.
	await sleep(2500);

	return {
		room,
		souvenirs,
		get profile() { return profile; },
		get guestToken() { return token; },
		owned: () => [...(profile?.cosmetics?.owned || [])],
		equipped: () => ({ ...(profile?.cosmetics?.equipped || {}) }),
		// The compact loadout wire every peer in the room reads off the schema.
		wireFor: (sessionId) => room.state.players.get(sessionId)?.cosmetics ?? null,
		equip: async (id) => { room.send('equip-cosmetic', { id }); await sleep(1500); },
		leave: async () => { try { await room.leave(true); } catch { /* already gone */ } await sleep(300); },
	};
}

async function main() {
	const configServer = createServer((req, res) => {
		res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
		res.end(JSON.stringify(configDoc()));
	});
	await new Promise((r) => configServer.listen(CONFIG_PORT, '127.0.0.1', r));
	console.log(`${at()} event config on :${CONFIG_PORT} (window: ${windowState})`);

	startServer();
	if (!await waitForHealth(60_000)) throw new Error('game server never came up');
	console.log(`${at()} game server up on :${MP_PORT}`);

	try {
		// ── 1. live window ─────────────────────────────────────────────────────
		const alice = await join({ name: 'Alice' });
		check('live window: granted on join', alice.souvenirs.length === 1,
			`announcements=${alice.souvenirs.length}`);
		check('live window: the announcement names the souvenir',
			alice.souvenirs[0]?.id === SOUVENIR_ID,
			JSON.stringify(alice.souvenirs[0] || null));
		check('live window: owned exactly once', alice.owned().filter((i) => i === SOUVENIR_ID).length === 1,
			`owned=${JSON.stringify(alice.owned())}`);
		check('live window: not auto-equipped over the player\'s own fit',
			alice.equipped()[SLOT] !== SOUVENIR_ID,
			`${SLOT}=${alice.equipped()[SLOT]}`);

		await alice.equip(SOUVENIR_ID);
		check('live window: it equips', alice.equipped()[SLOT] === SOUVENIR_ID,
			JSON.stringify(alice.equipped()));
		check('live window: published on the shared schema',
			String(alice.wireFor(alice.room.sessionId) || '').split(',').includes(SOUVENIR_ID),
			`wire=${alice.wireFor(alice.room.sessionId)}`);

		const aliceToken = alice.guestToken;
		check('live window: the server issued a durable identity', !!aliceToken);

		// ── 2. peer visibility ─────────────────────────────────────────────────
		const bob = await join({ name: 'Bob' });
		await sleep(1500);
		const seenByBob = bob.wireFor(alice.room.sessionId);
		check('another player sees the souvenir on the wearer',
			String(seenByBob || '').split(',').includes(SOUVENIR_ID),
			`peer wire=${seenByBob}`);
		check('the peer was granted their own copy too (they are also here)',
			bob.souvenirs.length === 1 && bob.owned().includes(SOUVENIR_ID),
			`announcements=${bob.souvenirs.length}`);
		await bob.leave();

		// ── 3. wrong world, same instant ───────────────────────────────────────
		await alice.leave();
		const aliceElsewhere = await join({ coin: OTHER_MINT, guestToken: aliceToken, name: 'Alice' });
		check('a different world grants nothing, even while the event is live',
			aliceElsewhere.souvenirs.length === 0,
			`announcements=${aliceElsewhere.souvenirs.length}`);
		await aliceElsewhere.leave();

		const carolElsewhere = await join({ coin: OTHER_MINT, name: 'Carol' });
		check('a player who was never in the event world owns nothing',
			carolElsewhere.souvenirs.length === 0 && !carolElsewhere.owned().includes(SOUVENIR_ID),
			`owned=${JSON.stringify(carolElsewhere.owned())}`);
		await carolElsewhere.leave();

		// ── 4. reconnect as the same account ───────────────────────────────────
		const aliceAgain = await join({ guestToken: aliceToken, name: 'Alice' });
		check('rejoin: no second announcement', aliceAgain.souvenirs.length === 0,
			`announcements=${aliceAgain.souvenirs.length}`);
		check('rejoin: still owned exactly once',
			aliceAgain.owned().filter((i) => i === SOUVENIR_ID).length === 1,
			`owned=${JSON.stringify(aliceAgain.owned())}`);
		check('rejoin: still worn, so the equip persisted across the reconnect',
			aliceAgain.equipped()[SLOT] === SOUVENIR_ID,
			JSON.stringify(aliceAgain.equipped()));

		// ── 5. closed window ───────────────────────────────────────────────────
		windowState = 'ended';
		console.log(`${at()} window flipped to ENDED; waiting out the ${TTL_MS}ms config TTL`);
		await sleep(TTL_MS + 2000);

		const dave = await join({ name: 'Dave' });
		check('closed window: a new player is granted nothing',
			dave.souvenirs.length === 0 && !dave.owned().includes(SOUVENIR_ID),
			`announcements=${dave.souvenirs.length} owned=${JSON.stringify(dave.owned())}`);
		check('closed window: they cannot equip what they were never granted',
			await (async () => {
				await dave.equip(SOUVENIR_ID);
				return dave.equipped()[SLOT] !== SOUVENIR_ID;
			})(),
			`${SLOT}=${dave.equipped()[SLOT]}`);
		await dave.leave();

		await aliceAgain.leave();
		const aliceAfter = await join({ guestToken: aliceToken, name: 'Alice' });
		check('closed window: an earlier attendee still owns it',
			aliceAfter.owned().includes(SOUVENIR_ID), `owned=${JSON.stringify(aliceAfter.owned())}`);
		check('closed window: and is still wearing it',
			aliceAfter.equipped()[SLOT] === SOUVENIR_ID, JSON.stringify(aliceAfter.equipped()));
		// Unequip and re-equip after the event to prove ownership is not time-scoped.
		await aliceAfter.equip('head-none');
		await aliceAfter.equip(SOUVENIR_ID);
		check('closed window: they can still take it off and put it back on',
			aliceAfter.equipped()[SLOT] === SOUVENIR_ID, JSON.stringify(aliceAfter.equipped()));
		await aliceAfter.leave();
	} finally {
		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);
});