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.

18.3 KB
Raw Blame
// ClashRoom, the live arena for Coin Wars (community-vs-community battles).
//
// Two coin communities meet here. A fighter joins FOR the coin they hold (proven by
// the same holder pass that gates that coin's Holders world), is seated on that
// faction, and fights the other community in a shared 3D arena. The room is a thin
// validator-and-replicator over two pure cores:
//   • combat.js, picks which enemy a swing lands on, from authoritative positions.
//   • clash.js, the match: friendly-fire rules, kill scoring, respawns, the round
//                   clock, sudden death, and the final result.
// Neither core touches the network or the schema, so the rules are unit-tested in
// isolation (tests/clash-match.test.js); this file just feeds them validated input
// and mirrors their state onto the wire.
//
// Matchmaking: rooms are defined with filterBy(['matchKey']) so every fighter who
// passes the same matchKey lands in the same arena instance, the /wars lobby mints a
// matchKey for a challenge and hands it to both communities.

import { Room } from '@colyseus/core';
import { ClashState, ClashFighter } from '../clash-schemas.js';
import { ClashMatch, ClashPhase, CLASH_DEFAULTS } from '../clash.js';
import { selectTarget } from '../combat.js';
import { verifyHolderPass } from '../holder-pass.js';
import { verifyPlayPass } from '../play-pass.js';
import { installUnknownMessageGuard } from '../room-compat.js';
import { cleanAvatarUrl } from '../avatar-url.js';
import { reportBattle } from '../war-report.js';
import { verifyWarTicket } from '../war-ticket.js';
import { publishWarLive, clearWarLive, HEARTBEAT_MS } from '../war-live.js';
import { publishFeedEvent } from '../feed.js';

const PLAY_GATE_MINT = (process.env.PLAY_GATE_MINT || process.env.THREE_MINT || '').trim();
const PLAY_GATE_MIN = Number(process.env.PLAY_GATE_MIN) > 0 ? Number(process.env.PLAY_GATE_MIN) : 1;

const MAX_CLIENTS = CLASH_DEFAULTS.maxPerTeam * 2;
const PATCH_RATE_MS = 1000 / 15;       // 15 Hz state deltas, like WalkRoom
const LOGIC_TICK_MS = 200;             // 5 Hz match logic (respawns, clock, phase)
const MOVE_RATE_HZ = 20;               // accepted moves/sec/client
const ATTACK_COOLDOWN_MS = 450;        // min time between a fighter's swings
const MAX_STEP_M = 3;                  // teleport reject (per accepted move)
const ARENA_BOUND_M = 60;              // square arena half-extent
const SPAWN_OFFSET = 22;               // each faction spawns this far up/down the z axis
const MOTION_VALUES = new Set(['idle', 'walk', 'run']);

// The arena weapon. Everyone fights with the same kit in v1, a mid-range blaster,
// so a clash is decided by positioning and teamwork, not gear. Real game constant
// (not a placeholder): the same {kind,dmg,range,aimTol} shape combat.js expects.
const CLASH_WEAPON = Object.freeze({ kind: 'ranged', dmg: 34, range: 26, aimTol: 0.32 });

function clean(s, max = 64) {
	return typeof s === 'string' ? s.replace(/[\u0000-]/g, '').trim().slice(0, max) : '';
}
function pickColor(seed) {
	let h = 0;
	for (let i = 0; i < seed.length; i++) h = (h * 31 + seed.charCodeAt(i)) >>> 0;
	return h & 0xffffff;
}

export class ClashRoom extends Room {
	// Admission. The platform play gate (if a game token is pinned) applies exactly as
	// in WalkRoom. Then the fighter must prove they hold the coin they want to fight
	// for: a holder pass whose mint equals their declared `coin`. That single check is
	// what makes a clash a battle BETWEEN communities, you can only wear a community's
	// colours if you actually hold its coin. The faction must also be one of the two in
	// this match. Throw on refusal so the client routes back to its gate.
	//
	// INSTANCE method, not static: Colyseus 0.16 calls a static onAuth as
	// onAuth(token, options, context) with the HTTP bearer token (undefined for
	// our clients) as the first argument, so the old static form crashed with a
	// TypeError on client.userData for EVERY join. Instance onAuth receives the
	// real client at WS join time. Mirrors the same fix in WalkRoom.
	onAuth(client, options) {
		if (PLAY_GATE_MINT) {
			const pass = verifyPlayPass(options?.playPass);
			if (!pass) throw new Error('play_pass_required');
			if (pass.mint !== PLAY_GATE_MINT) throw new Error('play_pass_mismatch');
			if (!(typeof pass.balance === 'number' && pass.balance >= PLAY_GATE_MIN)) throw new Error('play_pass_required');
			client.userData = { ...(client.userData || {}), account: pass.wallet };
		}

		const coin = clean(options?.coin, 64);
		if (!coin) throw new Error('clash_faction_required');
		const holder = verifyHolderPass(options?.holderPass);
		if (!holder) throw new Error('holder_pass_required');
		if (holder.mint !== coin) throw new Error('holder_pass_mismatch');
		client.userData = { ...(client.userData || {}), account: holder.wallet, faction: coin };
		return true;
	}

	onCreate(options) {
		this.setState(new ClashState());
		this.setPatchRate(PATCH_RATE_MS);
		this.maxClients = MAX_CLIENTS;
		this.autoDispose = true;
		// Unknown message types are ignored, never a session kill (room-compat.js).
		installUnknownMessageGuard(this, 'clash');

		// The two communities come from the SIGNED war ticket, never from the client.
		// filterBy(['matchKey']) means whoever joins a key first also creates the
		// room, so trusting client-supplied faction identities here would let one
		// fighter declare any opponent they liked and post a league result against a
		// community that never turned up. The API's matchmaker pairs the two
		// communities and seals them into the ticket (api/_lib/war-ticket.js); a
		// missing or forged one refuses room creation outright.
		const ticket = verifyWarTicket(options?.warTicket);
		if (!ticket) throw new Error('war_ticket_required');
		if (ticket.matchKey !== clean(options?.matchKey, 160)) throw new Error('war_ticket_mismatch');
		const a = { mint: ticket.a.mint, name: clean(ticket.a.name, 48), symbol: clean(ticket.a.symbol, 16), image: cleanAvatarUrl(ticket.a.image) };
		const b = { mint: ticket.b.mint, name: clean(ticket.b.name, 48), symbol: clean(ticket.b.symbol, 16), image: cleanAvatarUrl(ticket.b.image) };
		this.network = ticket.network || 'mainnet';
		this.matchKey = ticket.matchKey;
		this._reported = false;
		// Spectator state: the rolling knockdown feed and the heartbeat throttle for
		// the Redis snapshot the /play war portal polls (war-live.js).
		this._killFeed = [];
		this._lastLiveAt = 0;

		this.match = new ClashMatch({ factions: [a, b], config: {} });
		const s = this.state;
		s.scoreCap = this.match.cfg.scoreCap;
		s.aMint = a.mint; s.aName = a.name || a.symbol || 'Community'; s.aSymbol = a.symbol; s.aImage = a.image;
		s.bMint = b.mint; s.bName = b.name || b.symbol || 'Community'; s.bSymbol = b.symbol; s.bImage = b.image;
		s.phase = this.match.phase;

		this._moveCounters = new Map(); // sessionId → { windowStart, count }
		this._lastAttackAt = new Map(); // sessionId → epoch ms of last swing

		this.onMessage('move', (client, payload) => this._handleMove(client, payload));
		this.onMessage('attack', (client) => this._handleAttack(client));
		this.onMessage('emote', (client, payload) => this._handleEmote(client, payload));

		this.clock.setInterval(() => this._tick(), LOGIC_TICK_MS);
	}

	onJoin(client, options) {
		const faction = client.userData?.faction;
		// onAuth guaranteed the faction is the wallet's held coin; confirm it's one of
		// the two competitors in THIS match (a holder of an unrelated coin can't crash
		// a battle they're not part of).
		if (faction !== this.state.aMint && faction !== this.state.bMint) {
			throw new Error('clash_faction_mismatch');
		}
		const seat = this.match.addFighter(client.sessionId, faction, { combatLevel: 1, now: Date.now() });
		if (!seat) throw new Error('clash_faction_full');

		const f = new ClashFighter();
		f.id = client.sessionId;
		f.name = clean(options?.name, 24) || `guest-${client.sessionId.slice(0, 4)}`;
		f.color = pickColor(client.sessionId);
		f.avatar = cleanAvatarUrl(options?.avatar);
		f.agent = clean(options?.agent, 64);
		f.account = clean(client.userData?.account, 64);
		f.faction = faction;
		f.cosmetics = clean(options?.cosmetics, 256);
		this._spawn(f, faction);
		f.tsServer = Date.now();
		this.state.fighters.set(client.sessionId, f);

		console.log(`[clash ${this.roomId} ${this.matchKey}] +join ${client.sessionId} ${f.name} faction=${faction} (n=${this.state.fighters.size})`);

		// Arm the countdown the moment both communities have fielded a fighter.
		if (this.match.beginCountdown(Date.now())) this._mirror();
		// A new fighter changes the roster the portal board shows, so refresh the
		// spectator snapshot immediately rather than waiting out the heartbeat.
		this._publishLive(true);
	}

	onLeave(client) {
		const f = this.state.fighters.get(client.sessionId);
		const faction = f?.faction;
		this.match.removeFighter(client.sessionId);
		this.state.fighters.delete(client.sessionId);
		this._moveCounters.delete(client.sessionId);
		this._lastAttackAt.delete(client.sessionId);

		// A community that empties out mid-battle forfeits to the other side, so a
		// disconnect-to-dodge never robs the opponent of a clean league win.
		if (faction && (this.match.phase === ClashPhase.LIVE || this.match.phase === ClashPhase.SUDDEN_DEATH)) {
			if (this.match.countFaction(faction) === 0) {
				this.match.forfeit(faction, Date.now());
				this._mirror();
				this._finishIfEnded();
			}
		}
	}

	// --- handlers -----------------------------------------------------------

	_handleMove(client, payload) {
		const f = this.state.fighters.get(client.sessionId);
		if (!f || f.dead) return;
		if (!this._moveOk(client.sessionId)) return;
		if (!payload || typeof payload !== 'object') return;
		const { x, y, z, yaw, motion } = payload;
		if (![x, y, z, yaw].every((n) => typeof n === 'number' && Number.isFinite(n))) return;

		// Teleport reject: keep yaw/motion (legit on respawn) but pin position.
		if (Math.hypot(x - f.x, z - f.z) > MAX_STEP_M) {
			f.yaw = yaw;
			if (MOTION_VALUES.has(motion)) f.motion = motion;
			f.tsServer = Date.now();
			return;
		}
		f.x = Math.max(-ARENA_BOUND_M, Math.min(ARENA_BOUND_M, x));
		f.z = Math.max(-ARENA_BOUND_M, Math.min(ARENA_BOUND_M, z));
		f.y = Math.max(-4, Math.min(8, y));
		f.yaw = yaw;
		if (MOTION_VALUES.has(motion)) f.motion = motion;
		f.tsServer = Date.now();
	}

	// A swing. The client only declares intent; the SERVER picks the target from
	// authoritative positions (combat.selectTarget over living enemies in range +
	// arc), resolves it through the match engine (which owns friendly fire, vitals
	// and scoring), then broadcasts the hit feedback. The client never claims a hit.
	_handleAttack(client) {
		const attacker = this.state.fighters.get(client.sessionId);
		if (!attacker || attacker.dead) return;
		if (this.match.phase !== ClashPhase.LIVE && this.match.phase !== ClashPhase.SUDDEN_DEATH) return;
		const now = Date.now();
		if (now - (this._lastAttackAt.get(client.sessionId) || 0) < ATTACK_COOLDOWN_MS) return;
		this._lastAttackAt.set(client.sessionId, now);

		// Candidates: living fighters on the OTHER faction. Friendly fire is rejected
		// by the engine too, but excluding teammates here keeps the aim-assist honest.
		const candidates = [];
		for (const [id, other] of this.state.fighters) {
			if (id === client.sessionId || other.dead || other.faction === attacker.faction) continue;
			candidates.push({ id, x: other.x, z: other.z });
		}
		const hit = selectTarget({ x: attacker.x, z: attacker.z, yaw: attacker.yaw }, CLASH_WEAPON, candidates);
		// A whiff still broadcasts so peers see the muzzle/swing effect.
		if (!hit) { this.broadcast('clash:swing', { id: client.sessionId, hit: false }); return; }

		const res = this.match.resolveAttack(client.sessionId, hit.id, CLASH_WEAPON, { rng: Math.random, now });
		if (!res) { this.broadcast('clash:swing', { id: client.sessionId, hit: false }); return; }

		// Mirror the kill onto the schema so peers render the downed state + scoreboard.
		const target = this.state.fighters.get(hit.id);
		if (target && res.killed) {
			target.dead = true;
			target.deaths = this.match.fighters.get(hit.id)?.deaths ?? target.deaths;
			attacker.kills = this.match.fighters.get(client.sessionId)?.kills ?? attacker.kills;
			// Spectators watching from either world read this line, so it carries
			// display names and factions, never session ids.
			this._killFeed.push({
				ts: now,
				killer: attacker.name, killerFaction: attacker.faction,
				victim: target.name, victimFaction: target.faction,
			});
			if (this._killFeed.length > 24) this._killFeed.splice(0, this._killFeed.length - 24);
		}
		this.broadcast('clash:swing', {
			id: client.sessionId, hit: true, target: hit.id,
			dealt: res.dealt, killed: res.killed,
		});
		this._mirror();
		if (res.killed) this._publishLive(true);
		this._finishIfEnded();
	}

	_handleEmote(client, payload) {
		const f = this.state.fighters.get(client.sessionId);
		if (!f) return;
		const name = clean(payload?.name, 24);
		if (!name) return;
		f.emote = name;
		f.emoteTs = Date.now();
	}

	// --- match loop ---------------------------------------------------------

	_tick() {
		const now = Date.now();
		const ev = this.match.tick(now);
		// Bring respawned fighters back to a spawn point on the schema.
		for (const id of ev.respawns) {
			const f = this.state.fighters.get(id);
			if (f) { f.dead = false; this._spawn(f, f.faction); f.tsServer = now; }
		}
		if (ev.started || ev.ended || ev.respawns.length) this._mirror();
		else this._mirror(true); // cheap clock-only mirror
		this._publishLive(ev.started || ev.ended);
		this._finishIfEnded();
	}

	// --- spectating ---------------------------------------------------------

	// Publish this battle to the live registry the /play war portal polls. Rate-
	// limited to one write per HEARTBEAT_MS unless `force` (a join, a knockdown, a
	// phase change) makes the snapshot materially newer than the clock alone.
	_publishLive(force = false) {
		const now = Date.now();
		if (!force && now - this._lastLiveAt < HEARTBEAT_MS) return;
		this._lastLiveAt = now;
		publishWarLive(this._liveSnapshot(now));
	}

	// The spectator's view of this battle: text and numbers only, everything the
	// portal board renders without joining the room. Deliberately small, it is
	// written every couple of seconds for the whole length of a war.
	_liveSnapshot(now = Date.now()) {
		const s = this.state;
		let aFighters = 0;
		let bFighters = 0;
		for (const [, f] of s.fighters) {
			if (f.faction === s.aMint) aFighters++;
			else if (f.faction === s.bMint) bFighters++;
		}
		return {
			matchKey: this.matchKey,
			network: this.network,
			roomId: this.roomId,
			phase: s.phase,
			scoreCap: s.scoreCap,
			startedAt: s.startedAt,
			endsAt: s.endsAt,
			countdownEndsAt: s.countdownEndsAt,
			winner: s.winner || '',
			a: { mint: s.aMint, name: s.aName, symbol: s.aSymbol, image: s.aImage, score: s.aScore, fighters: aFighters },
			b: { mint: s.bMint, name: s.bName, symbol: s.bSymbol, image: s.bImage, score: s.bScore, fighters: bFighters },
			kills: this._killFeed,
			updatedAt: now,
		};
	}

	// Mirror the authoritative engine state onto the wire schema. `clockOnly` skips
	// the per-fighter sync (positions ride their own move patches) for the common
	// idle tick, writing just the scores, phase and clock.
	_mirror(clockOnly = false) {
		const s = this.state;
		const [fa, fb] = this.match._orderedFactions();
		s.phase = this.match.phase;
		s.aScore = fa.score;
		s.bScore = fb.score;
		s.startedAt = this.match.startedAt;
		s.endsAt = this.match.endsAt;
		s.countdownEndsAt = this.match.countdownEndsAt;
		if (this.match.phase === ClashPhase.ENDED) {
			s.winner = this.match.winner || '';
			s.mvpId = this.match.result(Date.now())?.mvp?.id || '';
		}
		if (clockOnly) return;
	}

	// Persist the result to the league ledger exactly once, then lock the room so it
	// disposes after players file out. The live winner is already on the schema; this
	// is the durable write the /wars standings recompute from.
	_finishIfEnded() {
		if (this.match.phase !== ClashPhase.ENDED || this._reported) return;
		this._reported = true;
		const result = this.match.result(Date.now());
		if (!result) return;
		this.broadcast('clash:end', {
			winner: result.winner, reason: result.reason,
			scoreA: this.state.aScore, scoreB: this.state.bScore, mvp: result.mvp,
		});
		// Fire-and-forget; reportBattle never throws.
		reportBattle({ ...result, matchKey: this.matchKey, network: this.network });
		// One last snapshot so a spectator's poll lands on the finished scoreline
		// (with the winner set) instead of the last live tick before the end.
		this._publishLive(true);
		// Echo the outcome into the site-wide activity feed, which is what carries
		// the result back into BOTH communities' worlds, the portal board reads the
		// ledger, the ticker reads this. Best-effort like every feed write.
		const winnerName = result.winner === this.state.aMint ? this.state.aName
			: result.winner === this.state.bMint ? this.state.bName : 'Draw';
		publishFeedEvent({
			type: 'war-result',
			actor: winnerName,
			winner: result.winner || 'draw',
			reason: result.reason || 'score_cap',
			a: { mint: this.state.aMint, name: this.state.aName, symbol: this.state.aSymbol, score: this.state.aScore },
			b: { mint: this.state.bMint, name: this.state.bName, symbol: this.state.bSymbol, score: this.state.bScore },
			matchKey: this.matchKey,
			network: this.network,
		}, this.matchKey);
		// Lock further joins; the room auto-disposes once empty.
		try { this.lock(); } catch { /* already locked */ }
	}

	// The arena has emptied out. Take the battle off the spectator board now
	// rather than leaving it advertised until the snapshot TTL expires.
	onDispose() {
		clearWarLive(this.matchKey);
	}

	// --- helpers ------------------------------------------------------------

	// Spawn a fighter on their faction's side of the arena, slightly scattered so two
	// fighters don't stack. Faction A spawns at -z, faction B at +z, facing the centre.
	_spawn(f, faction) {
		const side = faction === this.state.bMint ? 1 : -1;
		f.x = (Math.random() - 0.5) * 24;
		f.z = side * SPAWN_OFFSET + (Math.random() - 0.5) * 6;
		f.y = 0;
		f.yaw = side > 0 ? Math.PI : 0; // face the centre line
		f.motion = 'idle';
	}

	_moveOk(sessionId) {
		const now = Date.now();
		let c = this._moveCounters.get(sessionId);
		if (!c || now - c.windowStart >= 1000) { c = { windowStart: now, count: 0 }; this._moveCounters.set(sessionId, c); }
		if (c.count >= MOVE_RATE_HZ) return false;
		c.count++;
		return true;
	}
}