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
// Clash — the pure, server-authoritative core of Coin Wars (community-vs-community
// battles). Where combat.js owns a single swing's geometry and damage, clash.js
// owns the *match*: two coin communities as opposing factions, the kill score that
// decides which community wins, respawns, the round clock, sudden death, and the
// final result a war league is built from.
//
// Like combat.js this file touches NOTHING external — no network, no @colyseus
// schema, no world geometry. The ClashRoom feeds it validated hits (it already
// holds authoritative positions, so it runs combat.selectTarget itself) and ticks
// it with a clock; clash.js resolves damage through combat.js, keeps score, and
// reports phase transitions. Keeping it dependency-light (only combat.js, which is
// itself dependency-free) is deliberate: the whole match lifecycle is unit-testable
// in isolation, and the box's corrupted @colyseus/schema never enters the picture.
//
// A match is always exactly TWO factions, each a coin community keyed by its mint.
// Players fight FOR the coin they joined under; same-faction hits never land
// (friendly fire is off — you don't grief your own community). First faction to the
// score cap wins; if the clock runs out level, the match goes to sudden death where
// the next kill takes it.
import { rollDamage, applyDamage } from './combat.js';
// Match phases. A match walks lobby → countdown → live → (sudden_death) → ended.
// 'lobby' waits for both communities to field at least MIN_PER_TEAM fighters;
// 'countdown' is the brief lock-in before the gates open; 'live' is the fight;
// 'sudden_death' is overtime on a level clock; 'ended' is terminal.
export const ClashPhase = Object.freeze({
LOBBY: 'lobby',
COUNTDOWN: 'countdown',
LIVE: 'live',
SUDDEN_DEATH: 'sudden_death',
ENDED: 'ended',
});
// Tunables. These are the defaults a ClashRoom seeds a match with; every one can be
// overridden per match (e.g. a quick 1-min skirmish vs a 5-min war) via the config.
export const CLASH_DEFAULTS = Object.freeze({
scoreCap: 25, // kills for a community to win outright
durationMs: 5 * 60_000, // round clock; level score at expiry → sudden death
countdownMs: 5_000, // lock-in before the gates open
respawnMs: 6_000, // downed fighter returns after this long
minPerTeam: 1, // fighters each side needs before a match can start
maxPerTeam: 16, // roster cap per community (mirrors the room client cap)
maxHp: 100, // every fighter spawns at this
startArmor: 0, // armor is earned from loadout/cosmetics, not granted
});
// A single fighter in the match. Vitals live HERE (not on the wire-visible schema)
// for the same reason combat.js keeps them private: peers see `dead` and the
// scoreboard, never your exact HP. `combatLevel` gently scales the damage you deal
// (see combat.rollDamage). Plain mutable object — the engine owns it.
function makeFighter(id, faction, combatLevel, maxHp, startArmor) {
return {
id,
faction, // coin mint this fighter battles for
combatLevel: Math.max(1, combatLevel | 0),
hp: maxHp,
maxHp,
armor: Math.max(0, startArmor | 0),
dead: false,
respawnAt: 0, // epoch ms the engine will revive them (0 = alive)
kills: 0,
deaths: 0,
damage: 0, // total damage dealt to enemy fighters (MVP tiebreak)
joinedAt: 0,
};
}
export class ClashMatch {
// `config` overrides any CLASH_DEFAULTS. `factions` is the two competing coins:
// [{ mint, name, symbol, image }, { mint, ... }]. Both are required up front so
// the match always knows the two sides it is scoring, even before either fields
// a fighter (the lobby renders the matchup card from these).
constructor({ factions, config = {} } = {}) {
if (!Array.isArray(factions) || factions.length !== 2) {
throw new Error('ClashMatch requires exactly two factions');
}
const [a, b] = factions;
if (!a?.mint || !b?.mint || a.mint === b.mint) {
throw new Error('ClashMatch factions must be two distinct coin mints');
}
this.cfg = { ...CLASH_DEFAULTS, ...config };
// Faction state keyed by mint: identity (for the scoreboard/result) + live score.
this.factions = new Map();
for (const f of factions) {
this.factions.set(f.mint, {
mint: f.mint,
name: f.name || f.symbol || 'Community',
symbol: f.symbol || '',
image: f.image || '',
score: 0,
});
}
this.fighters = new Map(); // id → fighter
this.phase = ClashPhase.LOBBY;
this.startedAt = 0; // epoch ms the LIVE phase began (0 until started)
this.endsAt = 0; // epoch ms the round clock expires (0 until live)
this.countdownEndsAt = 0; // epoch ms COUNTDOWN flips to LIVE
this.endedAt = 0; // epoch ms the match ended
this.winner = null; // mint of the winning faction, or 'draw'
this.endReason = null; // 'score_cap' | 'timeout' | 'sudden_death' | 'forfeit'
}
// --- roster -------------------------------------------------------------
// Seat a fighter on a faction. Rejected (returns null) if the mint isn't one of
// the two competitors, the side is full, or they're already seated. The room
// gates *eligibility* (you hold the coin) before calling this; the engine only
// owns capacity + identity so the rules stay testable.
addFighter(id, factionMint, { combatLevel = 1, now = 0 } = {}) {
if (!id || !this.factions.has(factionMint)) return null;
if (this.fighters.has(id)) return this.fighters.get(id);
const onTeam = this.countFaction(factionMint);
if (onTeam >= this.cfg.maxPerTeam) return null;
const f = makeFighter(id, factionMint, combatLevel, this.cfg.maxHp, this.cfg.startArmor);
f.joinedAt = now;
this.fighters.set(id, f);
return f;
}
removeFighter(id) {
return this.fighters.delete(id);
}
countFaction(mint) {
let n = 0;
for (const f of this.fighters.values()) if (f.faction === mint) n++;
return n;
}
// Both communities have fielded enough fighters to start a fair match.
canStart() {
for (const mint of this.factions.keys()) {
if (this.countFaction(mint) < this.cfg.minPerTeam) return false;
}
return true;
}
// --- lifecycle ----------------------------------------------------------
// Begin the lock-in countdown. Idempotent and only valid from the lobby once
// both sides are staffed; returns true if it actually armed the countdown.
beginCountdown(now) {
if (this.phase !== ClashPhase.LOBBY || !this.canStart()) return false;
this.phase = ClashPhase.COUNTDOWN;
this.countdownEndsAt = now + this.cfg.countdownMs;
return true;
}
// Open the gates: COUNTDOWN → LIVE. Resets every fighter to full and starts the
// round clock. Callable directly (skipping countdown) for tests/instant matches.
start(now) {
if (this.phase === ClashPhase.LIVE) return false;
this.phase = ClashPhase.LIVE;
this.startedAt = now;
this.endsAt = now + this.cfg.durationMs;
for (const f of this.fighters.values()) this._revive(f);
return true;
}
// Resolve one attack the room has already targeted (it owns positions, so it runs
// combat.selectTarget and hands us the chosen victim). We enforce the match rules
// the geometry can't know: no hits before LIVE, none on the dead, and never on a
// teammate. On a kill we move the score, the meter the whole league is built on.
//
// Returns a result the room broadcasts as hit feedback, or null when the attack
// is a no-op (wrong phase, dead actor, friendly, self).
resolveAttack(attackerId, targetId, weapon, { rng = Math.random, now = 0 } = {}) {
if (this.phase !== ClashPhase.LIVE && this.phase !== ClashPhase.SUDDEN_DEATH) return null;
if (!attackerId || !targetId || attackerId === targetId) return null;
const attacker = this.fighters.get(attackerId);
const target = this.fighters.get(targetId);
if (!attacker || !target) return null;
if (attacker.dead || target.dead) return null;
if (attacker.faction === target.faction) return null; // friendly fire off
const dmg = rollDamage(weapon, attacker.combatLevel, rng);
const res = applyDamage(target, dmg);
attacker.damage += res.hpLost + res.armorAbsorbed;
let scored = false;
if (res.killed) {
target.dead = true;
target.respawnAt = now + this.cfg.respawnMs;
target.deaths += 1;
attacker.kills += 1;
const fac = this.factions.get(attacker.faction);
fac.score += 1;
scored = true;
// Sudden death: the first blood in overtime ends it immediately.
if (this.phase === ClashPhase.SUDDEN_DEATH) {
this._end(attacker.faction, 'sudden_death', now);
} else if (fac.score >= this.cfg.scoreCap) {
this._end(attacker.faction, 'score_cap', now);
}
}
return {
attacker: attackerId,
target: targetId,
faction: attacker.faction,
dealt: res.dealt,
armorAbsorbed: res.armorAbsorbed,
hpLost: res.hpLost,
targetHp: target.hp,
killed: res.killed,
scored,
scoreA: this._scoreOf(0),
scoreB: this._scoreOf(1),
};
}
// Advance time: revive anyone whose respawn has come due, run the countdown→live
// flip, and check the round clock. Returns the frame's events so the room can
// broadcast respawns and the phase change without re-reading internal state.
tick(now) {
const events = { phase: this.phase, respawns: [], ended: false, winner: null, started: false };
if (this.phase === ClashPhase.COUNTDOWN && now >= this.countdownEndsAt) {
this.start(now);
events.started = true;
events.phase = this.phase;
}
if (this.phase === ClashPhase.LIVE || this.phase === ClashPhase.SUDDEN_DEATH) {
for (const f of this.fighters.values()) {
if (f.dead && f.respawnAt && now >= f.respawnAt) {
this._revive(f);
events.respawns.push(f.id);
}
}
}
// Round clock. On expiry, the leader wins; a level score goes to sudden death
// (and only flips to a draw if a sudden-death round itself somehow expires,
// which a real match avoids by ending on first blood — see resolveAttack).
if (this.phase === ClashPhase.LIVE && now >= this.endsAt) {
const [fa, fb] = this._orderedFactions();
if (fa.score === fb.score) {
this.phase = ClashPhase.SUDDEN_DEATH;
} else {
this._end(fa.score > fb.score ? fa.mint : fb.mint, 'timeout', now);
}
}
if (this.phase === ClashPhase.ENDED) {
events.ended = true;
events.winner = this.winner;
}
events.phase = this.phase;
return events;
}
// Concede on behalf of a community — used when a side empties out mid-match (every
// fighter disconnected). The other community takes the win; if both are empty the
// match is a draw. Terminal.
forfeit(losingMint, now) {
if (this.phase === ClashPhase.ENDED) return;
const other = [...this.factions.keys()].find((m) => m !== losingMint);
this._end(other || 'draw', 'forfeit', now);
}
// --- snapshots ----------------------------------------------------------
// Live scoreboard for the HUD: each side's score + identity, the clock, and the
// per-fighter kill/death/damage lines. Cheap to call every tick.
scoreboard(now = 0) {
const [fa, fb] = this._orderedFactions();
const remainingMs = this.phase === ClashPhase.LIVE
? Math.max(0, this.endsAt - now)
: (this.phase === ClashPhase.SUDDEN_DEATH ? 0 : this.cfg.durationMs);
return {
phase: this.phase,
remainingMs,
factions: [this._facLine(fa), this._facLine(fb)],
fighters: [...this.fighters.values()].map((f) => ({
id: f.id, faction: f.faction, kills: f.kills, deaths: f.deaths,
damage: Math.round(f.damage), dead: f.dead,
})),
};
}
// The terminal result a war-standings ledger is built from. Only meaningful once
// `phase === ENDED`; returns null before then so callers can't persist a half-match.
result(now = 0) {
if (this.phase !== ClashPhase.ENDED) return null;
const [fa, fb] = this._orderedFactions();
return {
winner: this.winner, // mint | 'draw'
reason: this.endReason,
durationMs: Math.max(0, this.endedAt - this.startedAt),
endedAt: this.endedAt || now,
factions: [this._facResult(fa), this._facResult(fb)],
mvp: this._mvp(),
};
}
// --- internals ----------------------------------------------------------
_revive(f) {
f.hp = f.maxHp;
f.armor = Math.max(0, this.cfg.startArmor | 0);
f.dead = false;
f.respawnAt = 0;
}
_end(winnerMint, reason, now) {
if (this.phase === ClashPhase.ENDED) return;
this.phase = ClashPhase.ENDED;
this.winner = winnerMint;
this.endReason = reason;
this.endedAt = now;
}
// Stable ordering of the two factions by insertion order (faction A, faction B) so
// scoreA/scoreB and the scoreboard columns never swap between calls.
_orderedFactions() {
return [...this.factions.values()];
}
_scoreOf(index) {
return this._orderedFactions()[index]?.score ?? 0;
}
_facLine(fac) {
return {
mint: fac.mint, name: fac.name, symbol: fac.symbol, image: fac.image,
score: fac.score, alive: this._aliveCount(fac.mint), roster: this.countFaction(fac.mint),
};
}
_facResult(fac) {
const roster = [...this.fighters.values()].filter((f) => f.faction === fac.mint);
return {
mint: fac.mint, name: fac.name, symbol: fac.symbol,
score: fac.score,
kills: roster.reduce((s, f) => s + f.kills, 0),
deaths: roster.reduce((s, f) => s + f.deaths, 0),
fighters: roster.length,
};
}
_aliveCount(mint) {
let n = 0;
for (const f of this.fighters.values()) if (f.faction === mint && !f.dead) n++;
return n;
}
// Match MVP: most kills, then most damage, then fewest deaths. Null in an empty
// match. The winning community usually but not always houses the MVP.
_mvp() {
let best = null;
for (const f of this.fighters.values()) {
if (f.kills === 0 && f.damage === 0) continue;
if (!best
|| f.kills > best.kills
|| (f.kills === best.kills && f.damage > best.damage)
|| (f.kills === best.kills && f.damage === best.damage && f.deaths < best.deaths)) {
best = f;
}
}
return best ? { id: best.id, faction: best.faction, kills: best.kills, deaths: best.deaths, damage: Math.round(best.damage) } : null;
}
}