@vibemancer/core 0.1.0

package/src/stats.ts

@@ -0,0 +1,262 @@
+/**
+ * VIBEMANCER - FIGHT STATISTICS
+ *
+ * Extracts detailed per-bot statistics from a SimulateResult history.
+ * Used by testBot().simulate() and vibemancer trace for debugging.
+ */
+
+import type {GameState} from './types.js';
+import type {SimulateResult} from './engine/simulation.js';
+import {TICKS_PER_SECOND, SHIELD_MAX_BLOCK, SHIELD_DECAY_PER_SECOND, SHIELD_MIN_BLOCK} from './rules.js';
+
+/** Detailed statistics for one bot in a single match. */
+export interface FightStats
+{
+	/** Total damage dealt to the opponent. */
+	damageDealt: number;
+	/** Total damage taken from the opponent. */
+	damageTaken: number;
+	/** Number of missiles launched. */
+	missilesLaunched: number;
+	/** Number of missiles that dealt damage (hit the opponent). */
+	missileHits: number;
+	/** Hit rate (0-1). NaN if no missiles fired. */
+	hitRate: number;
+	/** Number of our missiles that hit while enemy was shielding. */
+	hitsEnemyShielded: number;
+	/** Number of our missiles that hit while enemy had no shield. */
+	hitsEnemyUnshielded: number;
+	/** Total raw damage our missiles would have dealt without shields. */
+	rawDamageDealt: number;
+	/** Damage blocked by enemy shields. */
+	damageBlockedByEnemy: number;
+	/** Percentage of our raw damage blocked by enemy shields (0-1). */
+	enemyBlockRate: number;
+	/** Number of times we were hit by enemy missiles. */
+	hitsReceived: number;
+	/** Number of hits received while shield was channeling. */
+	hitsShielded: number;
+	/** Number of hits received without shield. */
+	hitsUnshielded: number;
+	/** Total raw damage that hit us (before shield reduction). */
+	rawDamageReceived: number;
+	/** Total damage blocked by shields. */
+	damageBlocked: number;
+	/** Percentage of incoming raw damage that was blocked (0-1). */
+	blockRate: number;
+	/** Ticks spent in 'casting' state. */
+	castingTicks: number;
+	/** Ticks spent channeling shield. */
+	shieldTicks: number;
+	/** Ticks spent in GCD lockout. */
+	gcdTicks: number;
+	/** Ticks spent idle (not casting, channeling, or in GCD). */
+	idleTicks: number;
+	/** Number of times shield was activated. */
+	shieldCount: number;
+	/** Number of times blink was used. */
+	blinkCount: number;
+	/** Total match duration in ticks. */
+	totalTicks: number;
+}
+
+/**
+ * Compute the shield block percentage at a given channel duration.
+ * Same formula as the engine: starts at 90%, decays 20%/sec, min 30%.
+ */
+function shieldBlockPct(channelDurationTicks: number): number
+{
+	const channelSec = channelDurationTicks / TICKS_PER_SECOND;
+	return Math.max(SHIELD_MIN_BLOCK, SHIELD_MAX_BLOCK - SHIELD_DECAY_PER_SECOND * channelSec);
+}
+
+/**
+ * Extract fight statistics from a SimulateResult.
+ * Returns stats for wizard-1 (the bot under test).
+ */
+export function extractStats(result: SimulateResult): FightStats
+{
+	const history = result.history;
+	if (history.length === 0)
+	{
+		return emptyStats(result.ticks);
+	}
+
+	let damageDealt = 0;
+	let damageTaken = 0;
+	let missilesLaunched = 0;
+	let missileHits = 0;
+	let hitsEnemyShielded = 0;
+	let hitsEnemyUnshielded = 0;
+	let rawDamageDealt = 0;
+	let damageBlockedByEnemy = 0;
+	let hitsReceived = 0;
+	let hitsShielded = 0;
+	let hitsUnshielded = 0;
+	let rawDamageReceived = 0;
+	let damageBlocked = 0;
+	let castingTicks = 0;
+	let shieldTicks = 0;
+	let gcdTicks = 0;
+	let idleTicks = 0;
+	let shieldCount = 0;
+	let blinkCount = 0;
+
+	let prevState: GameState | null = null;
+
+	for (const state of history)
+	{
+		if (prevState)
+		{
+			// Damage dealt (enemy HP decreased)
+			const prevEnemy = prevState.enemies?.[0];
+			const curEnemy = state.enemies?.[0];
+			const prevEnemyHp = prevEnemy?.health ?? 0;
+			const curEnemyHp = curEnemy?.health ?? 0;
+			if (curEnemyHp < prevEnemyHp)
+			{
+				const dmg = prevEnemyHp - curEnemyHp;
+				damageDealt += dmg;
+				missileHits++;
+
+				if (prevEnemy?.channelingSpell === 'shield')
+				{
+					// Our missile hit while enemy was shielding
+					hitsEnemyShielded++;
+					const enemyBlockPct = shieldBlockPct(prevEnemy.channelDuration ?? 0);
+					const rawDmg = dmg / (1 - enemyBlockPct);
+					rawDamageDealt += rawDmg;
+					damageBlockedByEnemy += rawDmg - dmg;
+				}
+				else
+				{
+					// Hit without shield — raw = actual
+					hitsEnemyUnshielded++;
+					rawDamageDealt += dmg;
+				}
+			}
+
+			// Damage taken (our HP decreased)
+			if (state.health < prevState.health)
+			{
+				const dmg = prevState.health - state.health;
+				damageTaken += dmg;
+				hitsReceived++;
+
+				if (prevState.channelingSpell === 'shield')
+				{
+					// Hit while shielding — compute actual block amount
+					hitsShielded++;
+					const blockPct = shieldBlockPct(prevState.channelDuration ?? 0);
+					// damageTaken = rawDamage * (1 - blockPct)
+					// rawDamage = damageTaken / (1 - blockPct)
+					const rawDmg = dmg / (1 - blockPct);
+					const blocked = rawDmg - dmg;
+					rawDamageReceived += rawDmg;
+					damageBlocked += blocked;
+				}
+				else
+				{
+					// Hit without shield — raw damage = damage taken
+					hitsUnshielded++;
+					rawDamageReceived += dmg;
+				}
+			}
+
+			// Missile launches (new projectiles appearing)
+			const prevMyProj = prevState.myProjectiles?.length ?? 0;
+			const curMyProj = state.myProjectiles?.length ?? 0;
+			if (curMyProj > prevMyProj)
+			{
+				missilesLaunched += curMyProj - prevMyProj;
+			}
+
+			// State tracking
+			if (state.castingSpell) castingTicks++;
+			else if (state.channelingSpell === 'shield') shieldTicks++;
+			else if (state.gcdRemaining && state.gcdRemaining > 0) gcdTicks++;
+			else idleTicks++;
+
+			// Shield activations
+			if (state.channelingSpell === 'shield' && prevState.channelingSpell !== 'shield')
+			{
+				shieldCount++;
+			}
+
+			// Blink usage
+			if (prevState.castingSpell === 'blink' && state.castingSpell !== 'blink' && state.gcdRemaining && state.gcdRemaining > 0)
+			{
+				blinkCount++;
+			}
+		}
+
+		prevState = state;
+	}
+
+	const totalTicks = result.ticks;
+
+	return {
+		damageDealt,
+		damageTaken,
+		missilesLaunched,
+		missileHits,
+		hitRate: missilesLaunched > 0 ? missileHits / missilesLaunched : NaN,
+		hitsEnemyShielded,
+		hitsEnemyUnshielded,
+		rawDamageDealt,
+		damageBlockedByEnemy,
+		enemyBlockRate: rawDamageDealt > 0 ? damageBlockedByEnemy / rawDamageDealt : 0,
+		hitsReceived,
+		hitsShielded,
+		hitsUnshielded,
+		rawDamageReceived,
+		damageBlocked,
+		blockRate: rawDamageReceived > 0 ? damageBlocked / rawDamageReceived : 0,
+		castingTicks,
+		shieldTicks,
+		gcdTicks,
+		idleTicks,
+		shieldCount,
+		blinkCount,
+		totalTicks,
+	};
+}
+
+function emptyStats(totalTicks: number): FightStats
+{
+	return {
+		damageDealt: 0, damageTaken: 0,
+		missilesLaunched: 0, missileHits: 0, hitRate: NaN,
+		hitsEnemyShielded: 0, hitsEnemyUnshielded: 0,
+		rawDamageDealt: 0, damageBlockedByEnemy: 0, enemyBlockRate: 0,
+		hitsReceived: 0, hitsShielded: 0, hitsUnshielded: 0,
+		rawDamageReceived: 0, damageBlocked: 0, blockRate: 0,
+		castingTicks: 0, shieldTicks: 0, gcdTicks: 0, idleTicks: totalTicks,
+		shieldCount: 0, blinkCount: 0, totalTicks,
+	};
+}
+
+/** Format stats as a human-readable summary string. */
+export function formatStats(stats: FightStats, botName: string): string
+{
+	const lines: string[] = [];
+	const pct = (n: number): string => ((n / stats.totalTicks) * 100).toFixed(1);
+	const sec = (n: number): string => (n / TICKS_PER_SECOND).toFixed(1);
+
+	lines.push(`  ${botName} stats:`);
+	lines.push('    Offense:');
+	lines.push(`      Missiles: ${stats.missilesLaunched} fired, ${stats.missileHits} hit (${isNaN(stats.hitRate) ? 'N/A' : (stats.hitRate * 100).toFixed(0) + '%'})`);
+	lines.push(`      Damage:   ${stats.damageDealt.toFixed(1)} dealt${stats.damageBlockedByEnemy > 0 ? ` (${stats.rawDamageDealt.toFixed(1)} raw, ${stats.damageBlockedByEnemy.toFixed(1)} blocked by enemy = ${(stats.enemyBlockRate * 100).toFixed(0)}%)` : ''}`);
+	if (stats.missileHits > 0)
+	{
+		lines.push(`      Hits:     ${stats.hitsEnemyUnshielded} clean, ${stats.hitsEnemyShielded} shielded`);
+	}
+	lines.push('    Defense:');
+	lines.push(`      Hits taken: ${stats.hitsReceived} — ${stats.hitsUnshielded} unshielded, ${stats.hitsShielded} shielded`);
+	lines.push(`      Damage:   ${stats.damageTaken.toFixed(1)} taken${stats.damageBlocked > 0 ? ` (${stats.rawDamageReceived.toFixed(1)} raw, ${stats.damageBlocked.toFixed(1)} blocked = ${(stats.blockRate * 100).toFixed(0)}%)` : ''}`);
+	lines.push(`      Shield:   ${stats.shieldCount} activations, ${sec(stats.shieldTicks)}s channeled`);
+	lines.push(`      Blinks:   ${stats.blinkCount}`);
+	lines.push(`    Time: ${pct(stats.castingTicks)}% casting, ${pct(stats.shieldTicks)}% shielding, ${pct(stats.gcdTicks)}% GCD, ${pct(stats.idleTicks)}% idle`);
+
+	return lines.join('\n');
+}

package/src/testing.ts

@@ -0,0 +1,207 @@
+/**
+ * VIBEMANCER - TESTING UTILITIES
+ *
+ * Helpers for writing automated tests for your bot.
+ * Import from '@vibemancer/core' in your test files.
+ *
+ * @example
+ * import {testBot} from '@vibemancer/core';
+ * import {MyWizard} from '../src/bot';
+ *
+ * test('beats TargetDummy', async () => {
+ *   const result = await testBot(MyWizard).fight('TargetDummy');
+ *   expect(result.won).toBe(true);
+ * });
+ */
+
+import type {BotFunction} from './hooks/types.js';
+import type {WizardFunction} from './types.js';
+import type {FightResult, SimulateResult, MatchWinner, FightWinner} from './engine/simulation.js';
+import {fight, simulate, FIGHT_SPAWN_DISTANCES} from './engine/simulation.js';
+import {isNewStyleBot, wrapNewBot} from './hooks/bot-wrapper.js';
+import {extractStats} from './stats.js';
+import type {FightStats} from './stats.js';
+
+// Import all built-in bots
+import * as allBots from './bots/index.js';
+
+/** Result of a testBot().fight() call with convenience accessors. */
+export interface TestFightResult
+{
+	/** The raw FightResult from the simulation engine. */
+	raw: FightResult;
+	/** Overall winner: 'wizard-1' | 'wizard-2' | 'draw'. */
+	winner: FightWinner;
+	/** True if your bot won the fight. */
+	won: boolean;
+	/** True if your bot lost the fight. */
+	lost: boolean;
+	/** True if the fight was a draw. */
+	drawn: boolean;
+	/** Number of individual matches your bot won (out of 10). */
+	wins: number;
+	/** Number of individual matches your bot lost (out of 10). */
+	losses: number;
+	/** Number of individual matches that were draws. */
+	draws: number;
+}
+
+/** Result of a testBot().simulate() call with convenience accessors. */
+export interface TestSimulateResult
+{
+	/** The raw SimulateResult from the simulation engine. */
+	raw: SimulateResult;
+	/** Match winner. */
+	winner: MatchWinner;
+	/** True if your bot won. */
+	won: boolean;
+	/** True if your bot lost. */
+	lost: boolean;
+	/** True if the match was a draw or timeout. */
+	drawn: boolean;
+	/** Number of ticks the match lasted. */
+	ticks: number;
+	/** Your bot's remaining HP. */
+	myHealth: number;
+	/** Enemy's remaining HP. */
+	enemyHealth: number;
+	/** Detailed fight statistics (missiles, damage, shield usage, time breakdown). */
+	stats: FightStats;
+	/** Runtime errors thrown by bot or missile AI (empty if none). */
+	errors: Array<{tick: number; entityId: string; message: string}>;
+}
+
+/** Builder returned by testBot(). */
+export interface TestBotBuilder
+{
+	/**
+	 * Run a full fight (10 matches) against a named built-in bot.
+	 * @param opponent - Built-in bot name (e.g., 'Battlemage', 'TargetDummy').
+	 */
+	fight(opponent: string, options?: {seed?: number}): TestFightResult;
+
+	/**
+	 * Run a single match against a named built-in bot.
+	 * @param opponent - Built-in bot name.
+	 */
+	simulate(opponent: string, options?: {
+		seed?: number;
+		spawnDistance?: number;
+		maxTicks?: number;
+	}): TestSimulateResult;
+}
+
+/**
+ * Resolve a built-in bot name to a WizardFunction.
+ */
+function resolveBuiltinBot(name: string): WizardFunction
+{
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- dynamic bot lookup
+	const botMap = allBots as unknown as Record<string, WizardFunction | BotFunction>;
+	const bot = botMap[name];
+	if (!bot)
+	{
+		const available = Object.keys(botMap).filter((k) => typeof botMap[k] === 'function').join(', ');
+		throw new Error(`Unknown opponent "${name}". Available bots: ${available}`);
+	}
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- branching on length+shape detection
+	return typeof bot === 'function' && bot.length === 0 && isNewStyleBot(bot as BotFunction)
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- guarded by isNewStyleBot above
+		? wrapNewBot(bot as BotFunction)
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- legacy style bot after guard
+		: bot as WizardFunction;
+}
+
+/**
+ * Wrap a bot function for use with the simulation engine.
+ */
+function wrapBot(bot: WizardFunction | BotFunction): WizardFunction
+{
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- runtime shape detection
+	if (isNewStyleBot(bot as BotFunction))
+	{
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- guarded by isNewStyleBot above
+		return wrapNewBot(bot as BotFunction);
+	}
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- legacy style bot after guard
+	return bot as WizardFunction;
+}
+
+/**
+ * Create a test builder for your bot.
+ *
+ * @param bot - Your bot function (the same function you export from src/bot.ts).
+ * @returns A builder with .fight() and .simulate() methods.
+ *
+ * @example
+ * ```ts
+ * import {testBot} from '@vibemancer/core';
+ * import {MyWizard} from '../src/bot';
+ *
+ * test('beats TargetDummy', () => {
+ *   const result = testBot(MyWizard).fight('TargetDummy');
+ *   expect(result.won).toBe(true);
+ * });
+ *
+ * test('survives 10 seconds against Battlemage', () => {
+ *   const result = testBot(MyWizard).simulate('Battlemage', {maxTicks: 1000});
+ *   expect(result.myHealth).toBeGreaterThan(0);
+ * });
+ *
+ * test('kills at close range', () => {
+ *   const result = testBot(MyWizard).simulate('TargetDummy', {spawnDistance: 200});
+ *   expect(result.won).toBe(true);
+ *   expect(result.ticks).toBeLessThan(1000);
+ * });
+ * ```
+ */
+export function testBot(bot: WizardFunction | BotFunction): TestBotBuilder
+{
+	const wrappedBot = wrapBot(bot);
+
+	return {
+		fight(opponent: string, options?: {seed?: number}): TestFightResult
+		{
+			const opponentBot = resolveBuiltinBot(opponent);
+			const raw = fight(wrappedBot, opponentBot, {seed: options?.seed});
+
+			return {
+				raw,
+				winner: raw.winner,
+				won: raw.winner === 'wizard-1',
+				lost: raw.winner === 'wizard-2',
+				drawn: raw.winner === 'draw',
+				wins: raw.wizard1Wins,
+				losses: raw.wizard2Wins,
+				draws: raw.draws,
+			};
+		},
+
+		simulate(opponent: string, options?: {
+			seed?: number;
+			spawnDistance?: number;
+			maxTicks?: number;
+		}): TestSimulateResult
+		{
+			const opponentBot = resolveBuiltinBot(opponent);
+			const raw = simulate(wrappedBot, opponentBot, {
+				seed: options?.seed,
+				spawnDistance: options?.spawnDistance ?? FIGHT_SPAWN_DISTANCES[2], // 600 (middle distance)
+				maxTicks: options?.maxTicks,
+			});
+
+			return {
+				raw,
+				winner: raw.winner,
+				won: raw.winner === 'wizard-1',
+				lost: raw.winner === 'wizard-2',
+				drawn: raw.winner === null || raw.winner === 'draw',
+				ticks: raw.ticks,
+				myHealth: raw.finalState.health,
+				enemyHealth: raw.finalState.enemies?.[0]?.health ?? 0,
+				stats: extractStats(raw),
+				errors: raw.errors,
+			};
+		},
+	};
+}