@vibemancer/core 1.0.7 → 1.0.9

package/src/trace.ts

@@ -1,490 +1,497 @@
-/**
- * VIBEMANCER - FIGHT TRACE
- *
- * Extracts a structured event log from a SimulateResult history.
- * Both bots' actions are tracked: state changes, missile launches with
- * full config, hits, damage, dodge proximity, movement patterns.
- *
- * Used by:
- * - vibemancer trace (CLI debug command)
- * - scripts/fight-trace.ts (internal diagnostic)
- * - User tests that want event-level analysis
- */
-
-import type {GameState, ProjectileState, SimEvent} from './types.js';
-import type {SimulateResult, BotError} from './engine/simulation.js';
-import {distanceTo} from './utils/distance.js';
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-export interface TraceEvent
-{
-	tick: number;
-	/** 'W1' = wizard-1, 'W2' = wizard-2 */
-	actor: 'W1' | 'W2';
-	type: TraceEventType;
-	detail: string;
-}
-
-export type TraceEventType =
-	| 'STATE'        // State transition (idle→casting, etc.)
-	| 'FIRE'         // Missile launched (includes config + range)
-	| 'HIT'          // Damage dealt to opponent
-	| 'HURT'         // Damage taken from opponent
-	| 'DEATH'        // Wizard killed (missile hit)
-	| 'LAVA_DEATH'   // Wizard killed by lava (knockback/walk into border)
-	| 'SHIELD_BLOCK' // Shield absorbed damage (shows blocked + through amounts)
-	| 'KNOCKBACK'    // Knocked back by missile impact
-	| 'BLINK'        // Blink teleport (from → to positions)
-	| 'DODGE_START'  // Enemy missile enters 150u proximity
-	| 'DODGE_CLOSE'  // Enemy missile enters 50u proximity
-	| 'MOVE'         // Movement summary (every 100 ticks)
-	| 'ERROR'        // Bot or missile AI threw a runtime error
-	| 'WARNING';     // Common mistake detected (move/blink confusion, etc.)
-
-export interface TraceSummary
-{
-	winner: string;
-	ticks: number;
-	w1Name: string;
-	w2Name: string;
-	w1FinalHp: number;
-	w2FinalHp: number;
-	w1: TraceBotSummary;
-	w2: TraceBotSummary;
-}
-
-export interface TraceBotSummary
-{
-	missilesLaunched: number;
-	hits: number;
-	damageDealt: number;
-	damageReceived: number;
-	shields: number;
-	blinks: number;
-	dodgeEncounters: number;
-	causeOfDeath: 'missile' | 'lava' | 'alive' | 'timeout';
-	movement: {strafe: number; approach: number; retreat: number; still: number};
-}
-
-// ─── Event Extraction ────────────────────────────────────────────────────────
-
-/**
- * Extract a structured event log from simulation history.
- * Tracks both bots' state changes, missile launches (with full config + range),
- * hits, damage, dodge proximity, movement patterns, and runtime errors.
- */
-export function extractTraceEvents(history: GameState[], errors?: BotError[]): TraceEvent[]
-{
-	const events: TraceEvent[] = [];
-
-	let prevW1State = '';
-	let prevW2State = '';
-	let prevW1Health = history[0]?.health ?? 60;
-	let prevW2Health = history[0]?.enemies[0]?.health ?? 60;
-	let prevW1Spell = '';
-	let prevW2Spell = '';
-	const prevProjectileIds = new Set<string>();
-
-	for (let i = 0; i < history.length; i++)
-	{
-		const state = history[i]!;
-		const tick = state.tick;
-		const enemy = state.enemies[0]!;
-		const distance = distanceTo(state.position, enemy.position);
-
-		// --- W1 state transitions ---
-		const w1State = state.state;
-		const w1Spell = state.castingSpell ?? state.channelingSpell ?? '';
-		if (w1State !== prevW1State || w1Spell !== prevW1Spell)
-		{
-			let detail = `${prevW1State || '?'}→${w1State}`;
-			if (w1Spell) detail += ` (${w1Spell})`;
-			if (w1State === 'casting' && state.castDuration) detail += ` [${state.castDuration}t]`;
-			detail += ` dist=${distance.toFixed(0)}`;
-			events.push({tick, actor: 'W1', type: 'STATE', detail});
-		}
-
-		// --- W2 state transitions ---
-		const w2State = enemy.state;
-		const w2Spell = enemy.castingSpell ?? enemy.channelingSpell ?? '';
-		if (w2State !== prevW2State || w2Spell !== prevW2Spell)
-		{
-			let detail = `${prevW2State || '?'}→${w2State}`;
-			if (w2Spell) detail += ` (${w2Spell})`;
-			if (w2State === 'casting' && enemy.castDuration) detail += ` [${enemy.castDuration}t]`;
-			detail += ` dist=${distance.toFixed(0)}`;
-			events.push({tick, actor: 'W2', type: 'STATE', detail});
-		}
-
-		// --- Damage events ---
-		if (enemy.health < prevW2Health)
-		{
-			const dmg = prevW2Health - enemy.health;
-			events.push({
-				tick, actor: 'W1', type: 'HIT',
-				detail: `dealt ${dmg.toFixed(1)} → enemy HP=${enemy.health.toFixed(1)} dist=${distance.toFixed(0)}`,
-			});
-		}
-		if (state.health < prevW1Health)
-		{
-			const dmg = prevW1Health - state.health;
-			const stateTag = state.state === 'channeling' ? ' (SHIELDED)'
-				: state.state === 'casting' ? ` (CASTING ${state.castingSpell})`
-					: state.state === 'gcd_locked' ? ' (GCD)'
-						: ` (${state.state})`;
-			events.push({
-				tick, actor: 'W1', type: 'HURT',
-				detail: `took ${dmg.toFixed(1)} → HP=${state.health.toFixed(1)}${stateTag} dist=${distance.toFixed(0)}`,
-			});
-		}
-		// W2 damage taken = W1 damage dealt (already covered above as HIT)
-		// W2 damage dealt = W1 damage taken (already covered above as HURT)
-
-		// --- Missile launches (with full config) ---
-		const currentIds = new Set<string>();
-		for (const proj of state.projectiles)
-		{
-			currentIds.add(proj.id);
-			if (!prevProjectileIds.has(proj.id))
-			{
-				const owner: 'W1' | 'W2' = proj.ownerId === 'wizard-1' ? 'W1' : 'W2';
-				const range = (proj.speed * proj.remainingTicks).toFixed(0);
-				events.push({
-					tick, actor: owner, type: 'FIRE',
-					detail: `dmg=${proj.damage} spd=${proj.speed} turn=${proj.turnRate} life=${proj.remainingTicks} range=${range} dist=${distance.toFixed(0)}`,
-				});
-				// Warn if missile range < distance (will expire before reaching target)
-				if (proj.speed * proj.remainingTicks < distance * 0.8 && proj.turnRate >= 0)
-				{
-					events.push({
-						tick, actor: owner, type: 'WARNING',
-						detail: `missile range (${range}) may be too short for distance (${distance.toFixed(0)}) — consider increasing duration`,
-					});
-				}
-			}
-		}
-		prevProjectileIds.clear();
-		for (const id of currentIds) prevProjectileIds.add(id);
-
-		// --- Dodge proximity events (enemy missiles approaching W1) ---
-		if (i > 0)
-		{
-			const speed = Math.sqrt(state.velocity.x ** 2 + state.velocity.y ** 2);
-			for (const proj of state.projectiles)
-			{
-				if (proj.ownerId === 'wizard-1') continue;
-				const missileDistance = distanceTo(state.position, proj.position);
-				const prevProj = history[i - 1]!.projectiles.find((p) => p.id === proj.id);
-				const prevMissileDist = prevProj ? distanceTo(history[i - 1]!.position, prevProj.position) : Infinity;
-
-				if (missileDistance <= 150 && prevMissileDist > 150)
-				{
-					events.push({
-						tick, actor: 'W1', type: 'DODGE_START',
-						detail: formatDodgeDetail(state, proj, missileDistance, speed),
-					});
-				}
-				if (missileDistance <= 50 && prevMissileDist > 50)
-				{
-					events.push({
-						tick, actor: 'W1', type: 'DODGE_CLOSE',
-						detail: formatDodgeDetail(state, proj, missileDistance, speed),
-					});
-				}
-			}
-		}
-
-		// --- Simulation events (death, lava, shield block, knockback, blink) ---
-		if (state.events)
-		{
-			for (const ev of state.events)
-			{
-				const actor = actorFromId(ev);
-				if (ev.type === 'wizard-death')
-				{
-					events.push({tick, actor, type: 'DEATH', detail: `killed at (${ev.position.x.toFixed(0)},${ev.position.y.toFixed(0)})`});
-				}
-				else if (ev.type === 'wizard-lava-death')
-				{
-					events.push({tick, actor, type: 'LAVA_DEATH', detail: `walked/knocked into lava at (${ev.position.x.toFixed(0)},${ev.position.y.toFixed(0)})`});
-				}
-				else if (ev.type === 'shield-block')
-				{
-					events.push({tick, actor, type: 'SHIELD_BLOCK', detail: `blocked ${ev.damageBlocked.toFixed(1)} (${ev.damageThrough.toFixed(1)} through)`});
-				}
-				else if (ev.type === 'missile-hit')
-				{
-					const target = ev.targetId === 'wizard-1' ? 'W1' : 'W2';
-					const owner = ev.ownerId === 'wizard-1' ? 'W1' : 'W2';
-					if (ev.actualDamage < ev.damage)
-					{
-						events.push({tick, actor: target, type: 'HURT', detail: `hit by ${owner} missile: ${ev.damage} raw → ${ev.actualDamage.toFixed(1)} actual (shielded) dist=${distance.toFixed(0)}`});
-					}
-				}
-				else if (ev.type === 'blink')
-				{
-					const blinkDist = distanceTo(ev.from, ev.to);
-					events.push({tick, actor, type: 'BLINK', detail: `(${ev.from.x.toFixed(0)},${ev.from.y.toFixed(0)}) → (${ev.to.x.toFixed(0)},${ev.to.y.toFixed(0)}) ${blinkDist.toFixed(0)}u`});
-				}
-			}
-		}
-
-		// --- Movement summary every 100 ticks ---
-		if (tick > 0 && tick % 100 === 0)
-		{
-			const speed = Math.sqrt(state.velocity.x ** 2 + state.velocity.y ** 2);
-			const moveType = classifyMovement(state, enemy, speed);
-			const incomingMissiles = state.projectiles.filter((p) => p.ownerId !== 'wizard-1').length;
-			events.push({
-				tick, actor: 'W1', type: 'MOVE',
-				detail: `${moveType} spd=${speed.toFixed(2)} dist=${distance.toFixed(0)} missiles=${incomingMissiles} ${state.state} hp=${state.health.toFixed(1)}`,
-			});
-		}
-
-		prevW1State = w1State;
-		prevW2State = w2State;
-		prevW1Health = state.health;
-		prevW2Health = enemy.health;
-		prevW1Spell = w1Spell;
-		prevW2Spell = w2Spell;
-	}
-
-	// --- Inject runtime errors as ERROR events ---
-	if (errors && errors.length > 0)
-	{
-		for (const err of errors)
-		{
-			const actor: 'W1' | 'W2' = err.entityId === 'wizard-1' ? 'W1'
-				: err.entityId === 'wizard-2' ? 'W2'
-					: err.entityId.startsWith('missile') ? (/* missile errors attributed to owner */ 'W1') : 'W1';
-			events.push({
-				tick: err.tick,
-				actor,
-				type: 'ERROR',
-				detail: err.message,
-			});
-		}
-		// Re-sort by tick so errors appear in chronological order
-		events.sort((a, b) => a.tick - b.tick || (a.type === 'ERROR' ? 1 : 0));
-	}
-
-	return events;
-}
-
-// ─── Summary ─────────────────────────────────────────────────────────────────
-
-/**
- * Generate a summary from trace events and the simulation result.
- */
-export function summarizeTrace(
-	events: TraceEvent[],
-	result: SimulateResult,
-	w1Name: string,
-	w2Name: string,
-): TraceSummary
-{
-	const final = result.history[result.history.length - 1];
-
-	function botSummary(actor: 'W1' | 'W2'): TraceBotSummary
-	{
-		const myEvents = events.filter((e) => e.actor === actor);
-		const moveEvents = myEvents.filter((e) => e.type === 'MOVE');
-		return {
-			missilesLaunched: myEvents.filter((e) => e.type === 'FIRE').length,
-			hits: myEvents.filter((e) => e.type === 'HIT').length,
-			damageDealt: myEvents.filter((e) => e.type === 'HIT').reduce((sum, e) =>
-			{
-				const m = e.detail.match(/dealt ([\d.]+)/);
-				return sum + (m ? parseFloat(m[1]!) : 0);
-			}, 0),
-			damageReceived: myEvents.filter((e) => e.type === 'HURT').reduce((sum, e) =>
-			{
-				const m = e.detail.match(/took ([\d.]+)/);
-				return sum + (m ? parseFloat(m[1]!) : 0);
-			}, 0),
-			shields: myEvents.filter((e) => e.type === 'STATE' && e.detail.includes('shield')).length,
-			blinks: myEvents.filter((e) => e.type === 'STATE' && e.detail.includes('blink')).length,
-			dodgeEncounters: myEvents.filter((e) => e.type.startsWith('DODGE')).length,
-			causeOfDeath: myEvents.some((e) => e.type === 'LAVA_DEATH') ? 'lava'
-				: myEvents.some((e) => e.type === 'DEATH') ? 'missile'
-					: (final && ((actor === 'W1' ? final.health : final.enemies[0]?.health ?? 0) <= 0)) ? 'missile'
-						: result.winner === null ? 'timeout' : 'alive',
-			movement: {
-				strafe: moveEvents.filter((e) => e.detail.startsWith('STRAFE')).length,
-				approach: moveEvents.filter((e) => e.detail.startsWith('APPROACH')).length,
-				retreat: moveEvents.filter((e) => e.detail.startsWith('RETREAT')).length,
-				still: moveEvents.filter((e) => e.detail.startsWith('STILL')).length,
-			},
-		};
-	}
-
-	const winnerName = result.winner === 'wizard-1' ? w1Name
-		: result.winner === 'wizard-2' ? w2Name
-			: result.winner === 'draw' ? 'draw'
-				: 'timeout';
-
-	return {
-		winner: winnerName,
-		ticks: result.ticks,
-		w1Name,
-		w2Name,
-		w1FinalHp: final?.health ?? 0,
-		w2FinalHp: final?.enemies[0]?.health ?? 0,
-		w1: botSummary('W1'),
-		w2: botSummary('W2'),
-	};
-}
-
-// ─── Formatting ──────────────────────────────────────────────────────────────
-
-/** Format trace events as a human-readable string. */
-export function formatTraceEvents(events: TraceEvent[]): string
-{
-	return events.map((e) =>
-	{
-		const t = String(e.tick).padStart(5);
-		const a = e.actor.padEnd(2);
-		const ty = e.type.padEnd(12);
-		return `  T${t} ${a} ${ty} ${e.detail}`;
-	}).join('\n');
-}
-
-/** Format a full trace summary as a human-readable string. */
-export function formatTraceSummary(summary: TraceSummary): string
-{
-	const {w1Name, w2Name, w1, w2} = summary;
-	function formatBot(name: string, b: TraceBotSummary): string
-	{
-		const hitPct = b.missilesLaunched > 0 ? ((b.hits / b.missilesLaunched) * 100).toFixed(0) : 'N/A';
-		const death = b.causeOfDeath === 'lava' ? ' [LAVA DEATH]'
-			: b.causeOfDeath === 'missile' ? ' [KILLED]'
-				: b.causeOfDeath === 'timeout' ? '' : '';
-		return `  ${name}: ${b.missilesLaunched}m ${b.hits}h (${hitPct}%), ${b.damageDealt.toFixed(1)} dealt, ${b.damageReceived.toFixed(1)} taken, ${b.shields}s ${b.blinks}b${death}`;
-	}
-	const lines = [
-		`  Winner: ${summary.winner} @ T${summary.ticks}`,
-		`  Final HP: ${w1Name}=${summary.w1FinalHp.toFixed(1)}, ${w2Name}=${summary.w2FinalHp.toFixed(1)}`,
-		'',
-		formatBot(w1Name, w1),
-		formatBot(w2Name, w2),
-		'',
-		`  ${w1Name} movement: ${w1.movement.approach} approach, ${w1.movement.strafe} strafe, ${w1.movement.retreat} retreat, ${w1.movement.still} still | ${w1.dodgeEncounters} dodge encounters`,
-	];
-	return lines.join('\n');
-}
-
-/**
- * Generate diagnostic tips based on trace analysis.
- * Identifies common problems and suggests fixes.
- * Returns an array of human-readable tips (empty if no issues found).
- */
-export function diagnoseTrace(events: TraceEvent[], summary: TraceSummary): string[]
-{
-	const tips: string[] = [];
-	const {w1} = summary;
-
-	// Check for runtime errors
-	const errors = events.filter((e) => e.actor === 'W1' && e.type === 'ERROR');
-	if (errors.length > 0)
-	{
-		const firstErr = errors[0]!;
-		tips.push(`BOT ERROR: Your bot threw "${firstErr.detail}" on tick ${firstErr.tick}. The bot does nothing when it throws. Fix this first.`);
-		if (errors.length > 1) tips.push(`  (${errors.length} total errors — likely the same bug repeating every tick)`);
-	}
-
-	// Check for range warnings
-	const rangeWarnings = events.filter((e) => e.actor === 'W1' && e.type === 'WARNING' && e.detail.includes('range'));
-	if (rangeWarnings.length > 0)
-	{
-		tips.push(`RANGE: ${rangeWarnings.length} of your missiles had range shorter than target distance. Increase missile duration or get closer before firing.`);
-	}
-
-	// No missiles fired
-	if (w1.missilesLaunched === 0 && errors.length === 0)
-	{
-		tips.push('NO OFFENSE: Your bot fired 0 missiles. Check that you return missile() when useTicksUntilReady() === 0.');
-	}
-
-	// Very low hit rate
-	if (w1.missilesLaunched >= 3 && w1.hits === 0)
-	{
-		tips.push(`ACCURACY: Fired ${w1.missilesLaunched} missiles but 0 hit. Consider: more homing (higher turnRate), or use getLeadPosition() for straight missiles, or get closer.`);
-	}
-	else if (w1.missilesLaunched >= 5 && w1.hits / w1.missilesLaunched < 0.25)
-	{
-		tips.push(`LOW ACCURACY: Only ${((w1.hits / w1.missilesLaunched) * 100).toFixed(0)}% hit rate. Try increasing turnRate for more homing, or use getLeadPosition() for prediction.`);
-	}
-
-	// No shields against incoming damage
-	if (w1.damageReceived > 20 && w1.shields === 0)
-	{
-		tips.push(`NO DEFENSE: Took ${w1.damageReceived.toFixed(0)} damage with 0 shields. Use useThreats() to detect incoming missiles and shield() when you can't dodge.`);
-	}
-
-	// Too much idle time
-	if (summary.ticks > 500)
-	{
-		const idleMovements = w1.movement.still;
-		const totalMovements = idleMovements + w1.movement.approach + w1.movement.strafe + w1.movement.retreat;
-		if (totalMovements > 0 && idleMovements / totalMovements > 0.5)
-		{
-			tips.push(`IDLE: Your bot was stationary ${((idleMovements / totalMovements) * 100).toFixed(0)}% of the time. Move to dodge missiles and close distance.`);
-		}
-	}
-
-	return tips;
-}
-
-/** Format diagnostic tips as a human-readable string. */
-export function formatDiagnosis(tips: string[]): string
-{
-	if (tips.length === 0) return '';
-	const lines = ['  Diagnosis:'];
-	for (const tip of tips)
-	{
-		lines.push(`    - ${tip}`);
-	}
-	return lines.join('\n');
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-function formatDodgeDetail(state: GameState, proj: ProjectileState, missileDistance: number, speed: number): string
-{
-	const angle = dodgeAngle(state.velocity, proj.rotation);
-	return `missile at ${missileDistance.toFixed(0)}u rot=${proj.rotation.toFixed(0)}° dodge_angle=${angle.toFixed(0)}° ` +
-		`spd=${speed.toFixed(2)} ${state.state}`;
-}
-
-function dodgeAngle(wizardVelocity: {x: number; y: number}, missileRotation: number): number
-{
-	const speed = Math.sqrt(wizardVelocity.x ** 2 + wizardVelocity.y ** 2);
-	if (speed < 0.01) return 0;
-	const missileRad = missileRotation * (Math.PI / 180);
-	const dot = Math.cos(missileRad) * (wizardVelocity.x / speed) + Math.sin(missileRad) * (wizardVelocity.y / speed);
-	return Math.acos(Math.max(-1, Math.min(1, Math.abs(dot)))) * (180 / Math.PI);
-}
-
-function actorFromId(ev: SimEvent): 'W1' | 'W2'
-{
-	if ('wizardId' in ev) return ev.wizardId === 'wizard-1' ? 'W1' : 'W2';
-	if ('ownerId' in ev) return ev.ownerId === 'wizard-1' ? 'W1' : 'W2';
-	return 'W1';
-}
-
-function classifyMovement(state: GameState, enemy: GameState['enemies'][0], speed: number): string
-{
-	if (speed < 0.1) return 'STILL';
-	const toEnemyAngle = Math.atan2(enemy.position.y - state.position.y, enemy.position.x - state.position.x);
-	const moveAngle = Math.atan2(state.velocity.y, state.velocity.x);
-	let angleDiff = ((moveAngle - toEnemyAngle) * 180 / Math.PI) % 360;
-	if (angleDiff > 180) angleDiff -= 360;
-	if (angleDiff < -180) angleDiff += 360;
-	const absAngle = Math.abs(angleDiff);
-	if (absAngle < 30) return 'APPROACH';
-	if (absAngle > 150) return 'RETREAT';
-	if (absAngle >= 60 && absAngle <= 120) return 'STRAFE';
-	if (absAngle < 60) return 'APPROACH+STRAFE';
-	return 'RETREAT+STRAFE';
-}
+/**
+ * VIBEMANCER - FIGHT TRACE
+ *
+ * Extracts a structured event log from a SimulateResult history.
+ * Both bots' actions are tracked: state changes, missile launches with
+ * full config, hits, damage, dodge proximity, movement patterns.
+ *
+ * Used by:
+ * - vibemancer trace (CLI debug command)
+ * - scripts/fight-trace.ts (internal diagnostic)
+ * - User tests that want event-level analysis
+ */
+
+import type {GameState, ProjectileState, SimEvent} from './types.js';
+import type {SimulateResult, BotError} from './engine/simulation.js';
+import {distanceTo} from './utils/distance.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TraceEvent
+{
+	tick: number;
+	/** 'W1' = wizard-1, 'W2' = wizard-2 */
+	actor: 'W1' | 'W2';
+	type: TraceEventType;
+	detail: string;
+}
+
+export type TraceEventType =
+	| 'STATE'        // State transition (idle→casting, etc.)
+	| 'FIRE'         // Missile launched (includes config + range)
+	| 'HIT'          // Damage dealt to opponent
+	| 'HURT'         // Damage taken from opponent
+	| 'DEATH'        // Wizard killed (missile hit)
+	| 'LAVA_DEATH'   // Wizard killed by lava (knockback/walk into border)
+	| 'SHIELD_BLOCK' // Shield absorbed damage (shows blocked + through amounts)
+	| 'KNOCKBACK'    // Knocked back by missile impact
+	| 'BLINK'        // Blink teleport (from → to positions)
+	| 'DODGE_START'  // Enemy missile enters 150u proximity
+	| 'DODGE_CLOSE'  // Enemy missile enters 50u proximity
+	| 'MOVE'         // Movement summary (every 100 ticks)
+	| 'ERROR'        // Bot or missile AI threw a runtime error
+	| 'WARNING';     // Common mistake detected (move/blink confusion, etc.)
+
+export interface TraceSummary
+{
+	winner: string;
+	ticks: number;
+	w1Name: string;
+	w2Name: string;
+	w1FinalHp: number;
+	w2FinalHp: number;
+	w1: TraceBotSummary;
+	w2: TraceBotSummary;
+}
+
+export interface TraceBotSummary
+{
+	missilesLaunched: number;
+	hits: number;
+	damageDealt: number;
+	damageReceived: number;
+	shields: number;
+	blinks: number;
+	dodgeEncounters: number;
+	causeOfDeath: 'missile' | 'lava' | 'alive' | 'timeout';
+	movement: {strafe: number; approach: number; retreat: number; still: number};
+}
+
+// ─── Event Extraction ────────────────────────────────────────────────────────
+
+/**
+ * Extract a structured event log from simulation history.
+ * Tracks both bots' state changes, missile launches (with full config + range),
+ * hits, damage, dodge proximity, movement patterns, and runtime errors.
+ */
+export function extractTraceEvents(history: GameState[], errors?: BotError[]): TraceEvent[]
+{
+	const events: TraceEvent[] = [];
+
+	let prevW1State = '';
+	let prevW2State = '';
+	let prevW1Health = history[0]?.health ?? 60;
+	let prevW2Health = history[0]?.enemies[0]?.health ?? 60;
+	let prevW1Spell = '';
+	let prevW2Spell = '';
+	const prevProjectileIds = new Set<string>();
+
+	for (let i = 0; i < history.length; i++)
+	{
+		const state = history[i]!;
+		const tick = state.tick;
+		const enemy = state.enemies[0]!;
+		const distance = distanceTo(state.position, enemy.position);
+
+		// --- W1 state transitions ---
+		const w1State = state.state;
+		const w1Spell = state.castingSpell ?? state.channelingSpell ?? '';
+		if (w1State !== prevW1State || w1Spell !== prevW1Spell)
+		{
+			let detail = `${prevW1State || '?'}→${w1State}`;
+			if (w1Spell) detail += ` (${w1Spell})`;
+			if (w1State === 'casting' && state.castDuration) detail += ` [${state.castDuration}t]`;
+			detail += ` dist=${distance.toFixed(0)}`;
+			events.push({tick, actor: 'W1', type: 'STATE', detail});
+		}
+
+		// --- W2 state transitions ---
+		const w2State = enemy.state;
+		const w2Spell = enemy.castingSpell ?? enemy.channelingSpell ?? '';
+		if (w2State !== prevW2State || w2Spell !== prevW2Spell)
+		{
+			let detail = `${prevW2State || '?'}→${w2State}`;
+			if (w2Spell) detail += ` (${w2Spell})`;
+			if (w2State === 'casting' && enemy.castDuration) detail += ` [${enemy.castDuration}t]`;
+			detail += ` dist=${distance.toFixed(0)}`;
+			events.push({tick, actor: 'W2', type: 'STATE', detail});
+		}
+
+		// --- Damage events ---
+		if (enemy.health < prevW2Health)
+		{
+			const dmg = prevW2Health - enemy.health;
+			events.push({
+				tick, actor: 'W1', type: 'HIT',
+				detail: `dealt ${dmg.toFixed(1)} → enemy HP=${enemy.health.toFixed(1)} dist=${distance.toFixed(0)}`,
+			});
+		}
+		if (state.health < prevW1Health)
+		{
+			const dmg = prevW1Health - state.health;
+			const stateTag = state.state === 'channeling' ? ' (SHIELDED)'
+				: state.state === 'casting' ? ` (CASTING ${state.castingSpell})`
+					: state.state === 'gcd_locked' ? ' (GCD)'
+						: ` (${state.state})`;
+			events.push({
+				tick, actor: 'W1', type: 'HURT',
+				detail: `took ${dmg.toFixed(1)} → HP=${state.health.toFixed(1)}${stateTag} dist=${distance.toFixed(0)}`,
+			});
+		}
+		// W2 damage taken = W1 damage dealt (already covered above as HIT)
+		// W2 damage dealt = W1 damage taken (already covered above as HURT)
+
+		// --- Missile launches (with full config) ---
+		const currentIds = new Set<string>();
+		for (const proj of state.projectiles)
+		{
+			currentIds.add(proj.id);
+			if (!prevProjectileIds.has(proj.id))
+			{
+				const owner: 'W1' | 'W2' = proj.ownerId === 'wizard-1' ? 'W1' : 'W2';
+				const range = (proj.speed * proj.remainingTicks).toFixed(0);
+				events.push({
+					tick, actor: owner, type: 'FIRE',
+					detail: `dmg=${proj.damage} spd=${proj.speed} turn=${proj.turnRate} life=${proj.remainingTicks} range=${range} dist=${distance.toFixed(0)}`,
+				});
+				// Warn if missile range < distance (will expire before reaching target)
+				if (proj.speed * proj.remainingTicks < distance * 0.8 && proj.turnRate >= 0)
+				{
+					events.push({
+						tick, actor: owner, type: 'WARNING',
+						detail: `missile range (${range}) may be too short for distance (${distance.toFixed(0)}) — consider increasing duration`,
+					});
+				}
+			}
+		}
+		prevProjectileIds.clear();
+		for (const id of currentIds) prevProjectileIds.add(id);
+
+		// --- Dodge proximity events (enemy missiles approaching W1) ---
+		if (i > 0)
+		{
+			const speed = Math.sqrt(state.velocity.x ** 2 + state.velocity.y ** 2);
+			for (const proj of state.projectiles)
+			{
+				if (proj.ownerId === 'wizard-1') continue;
+				const missileDistance = distanceTo(state.position, proj.position);
+				const prevProj = history[i - 1]!.projectiles.find((p) => p.id === proj.id);
+				const prevMissileDist = prevProj ? distanceTo(history[i - 1]!.position, prevProj.position) : Infinity;
+
+				if (missileDistance <= 150 && prevMissileDist > 150)
+				{
+					events.push({
+						tick, actor: 'W1', type: 'DODGE_START',
+						detail: formatDodgeDetail(state, proj, missileDistance, speed),
+					});
+				}
+				if (missileDistance <= 50 && prevMissileDist > 50)
+				{
+					events.push({
+						tick, actor: 'W1', type: 'DODGE_CLOSE',
+						detail: formatDodgeDetail(state, proj, missileDistance, speed),
+					});
+				}
+			}
+		}
+
+		// --- Simulation events (death, lava, shield block, knockback, blink) ---
+		if (state.events)
+		{
+			for (const ev of state.events)
+			{
+				const actor = actorFromId(ev);
+				if (ev.type === 'wizard-death')
+				{
+					events.push({tick, actor, type: 'DEATH', detail: `killed at (${ev.position.x.toFixed(0)},${ev.position.y.toFixed(0)})`});
+				}
+				else if (ev.type === 'wizard-lava-death')
+				{
+					events.push({tick, actor, type: 'LAVA_DEATH', detail: `walked/knocked into lava at (${ev.position.x.toFixed(0)},${ev.position.y.toFixed(0)})`});
+				}
+				else if (ev.type === 'shield-block')
+				{
+					events.push({tick, actor, type: 'SHIELD_BLOCK', detail: `blocked ${ev.damageBlocked.toFixed(1)} (${ev.damageThrough.toFixed(1)} through)`});
+				}
+				else if (ev.type === 'missile-hit')
+				{
+					const target = ev.targetId === 'wizard-1' ? 'W1' : 'W2';
+					const owner = ev.ownerId === 'wizard-1' ? 'W1' : 'W2';
+					if (ev.actualDamage < ev.damage)
+					{
+						events.push({tick, actor: target, type: 'HURT', detail: `hit by ${owner} missile: ${ev.damage} raw → ${ev.actualDamage.toFixed(1)} actual (shielded) dist=${distance.toFixed(0)}`});
+					}
+				}
+				else if (ev.type === 'blink')
+				{
+					const blinkDist = distanceTo(ev.from, ev.to);
+					events.push({tick, actor, type: 'BLINK', detail: `(${ev.from.x.toFixed(0)},${ev.from.y.toFixed(0)}) → (${ev.to.x.toFixed(0)},${ev.to.y.toFixed(0)}) ${blinkDist.toFixed(0)}u`});
+				}
+			}
+		}
+
+		// --- Movement summary every 100 ticks ---
+		if (tick > 0 && tick % 100 === 0)
+		{
+			const speed = Math.sqrt(state.velocity.x ** 2 + state.velocity.y ** 2);
+			const moveType = classifyMovement(state, enemy, speed);
+			const incomingMissiles = state.projectiles.filter((p) => p.ownerId !== 'wizard-1').length;
+			events.push({
+				tick, actor: 'W1', type: 'MOVE',
+				detail: `${moveType} spd=${speed.toFixed(2)} dist=${distance.toFixed(0)} missiles=${incomingMissiles} ${state.state} hp=${state.health.toFixed(1)}`,
+			});
+		}
+
+		prevW1State = w1State;
+		prevW2State = w2State;
+		prevW1Health = state.health;
+		prevW2Health = enemy.health;
+		prevW1Spell = w1Spell;
+		prevW2Spell = w2Spell;
+	}
+
+	// --- Inject runtime errors as ERROR events ---
+	if (errors && errors.length > 0)
+	{
+		for (const err of errors)
+		{
+			// A missile's throw is recorded against the PROJECTILE, and projectile ids are built
+			// as `missile-${wizard.id}-${tick}`, so the owner is in the middle of the string.
+			// This branch existed with the comment "missile errors attributed to owner" and
+			// both arms returned 'W1', so every missile fault in the game was blamed on wizard
+			// 1 — telling an idle bot it had thrown 1,333 times for its opponent's code.
+			const missileOwner = /^missile-(wizard-[12])-/.exec(err.entityId);
+			const actor: 'W1' | 'W2' = err.entityId === 'wizard-1' ? 'W1'
+				: err.entityId === 'wizard-2' ? 'W2'
+					: missileOwner ? (missileOwner[1] === 'wizard-2' ? 'W2' : 'W1')
+						: 'W1';
+			events.push({
+				tick: err.tick,
+				actor,
+				type: 'ERROR',
+				detail: err.message,
+			});
+		}
+		// Re-sort by tick so errors appear in chronological order
+		events.sort((a, b) => a.tick - b.tick || (a.type === 'ERROR' ? 1 : 0));
+	}
+
+	return events;
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a summary from trace events and the simulation result.
+ */
+export function summarizeTrace(
+	events: TraceEvent[],
+	result: SimulateResult,
+	w1Name: string,
+	w2Name: string,
+): TraceSummary
+{
+	const final = result.history[result.history.length - 1];
+
+	function botSummary(actor: 'W1' | 'W2'): TraceBotSummary
+	{
+		const myEvents = events.filter((e) => e.actor === actor);
+		const moveEvents = myEvents.filter((e) => e.type === 'MOVE');
+		return {
+			missilesLaunched: myEvents.filter((e) => e.type === 'FIRE').length,
+			hits: myEvents.filter((e) => e.type === 'HIT').length,
+			damageDealt: myEvents.filter((e) => e.type === 'HIT').reduce((sum, e) =>
+			{
+				const m = e.detail.match(/dealt ([\d.]+)/);
+				return sum + (m ? parseFloat(m[1]!) : 0);
+			}, 0),
+			damageReceived: myEvents.filter((e) => e.type === 'HURT').reduce((sum, e) =>
+			{
+				const m = e.detail.match(/took ([\d.]+)/);
+				return sum + (m ? parseFloat(m[1]!) : 0);
+			}, 0),
+			shields: myEvents.filter((e) => e.type === 'STATE' && e.detail.includes('shield')).length,
+			blinks: myEvents.filter((e) => e.type === 'STATE' && e.detail.includes('blink')).length,
+			dodgeEncounters: myEvents.filter((e) => e.type.startsWith('DODGE')).length,
+			causeOfDeath: myEvents.some((e) => e.type === 'LAVA_DEATH') ? 'lava'
+				: myEvents.some((e) => e.type === 'DEATH') ? 'missile'
+					: (final && ((actor === 'W1' ? final.health : final.enemies[0]?.health ?? 0) <= 0)) ? 'missile'
+						: result.winner === null ? 'timeout' : 'alive',
+			movement: {
+				strafe: moveEvents.filter((e) => e.detail.startsWith('STRAFE')).length,
+				approach: moveEvents.filter((e) => e.detail.startsWith('APPROACH')).length,
+				retreat: moveEvents.filter((e) => e.detail.startsWith('RETREAT')).length,
+				still: moveEvents.filter((e) => e.detail.startsWith('STILL')).length,
+			},
+		};
+	}
+
+	const winnerName = result.winner === 'wizard-1' ? w1Name
+		: result.winner === 'wizard-2' ? w2Name
+			: result.winner === 'draw' ? 'draw'
+				: 'timeout';
+
+	return {
+		winner: winnerName,
+		ticks: result.ticks,
+		w1Name,
+		w2Name,
+		w1FinalHp: final?.health ?? 0,
+		w2FinalHp: final?.enemies[0]?.health ?? 0,
+		w1: botSummary('W1'),
+		w2: botSummary('W2'),
+	};
+}
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+/** Format trace events as a human-readable string. */
+export function formatTraceEvents(events: TraceEvent[]): string
+{
+	return events.map((e) =>
+	{
+		const t = String(e.tick).padStart(5);
+		const a = e.actor.padEnd(2);
+		const ty = e.type.padEnd(12);
+		return `  T${t} ${a} ${ty} ${e.detail}`;
+	}).join('\n');
+}
+
+/** Format a full trace summary as a human-readable string. */
+export function formatTraceSummary(summary: TraceSummary): string
+{
+	const {w1Name, w2Name, w1, w2} = summary;
+	function formatBot(name: string, b: TraceBotSummary): string
+	{
+		const hitPct = b.missilesLaunched > 0 ? ((b.hits / b.missilesLaunched) * 100).toFixed(0) : 'N/A';
+		const death = b.causeOfDeath === 'lava' ? ' [LAVA DEATH]'
+			: b.causeOfDeath === 'missile' ? ' [KILLED]'
+				: b.causeOfDeath === 'timeout' ? '' : '';
+		return `  ${name}: ${b.missilesLaunched}m ${b.hits}h (${hitPct}%), ${b.damageDealt.toFixed(1)} dealt, ${b.damageReceived.toFixed(1)} taken, ${b.shields}s ${b.blinks}b${death}`;
+	}
+	const lines = [
+		`  Winner: ${summary.winner} @ T${summary.ticks}`,
+		`  Final HP: ${w1Name}=${summary.w1FinalHp.toFixed(1)}, ${w2Name}=${summary.w2FinalHp.toFixed(1)}`,
+		'',
+		formatBot(w1Name, w1),
+		formatBot(w2Name, w2),
+		'',
+		`  ${w1Name} movement: ${w1.movement.approach} approach, ${w1.movement.strafe} strafe, ${w1.movement.retreat} retreat, ${w1.movement.still} still | ${w1.dodgeEncounters} dodge encounters`,
+	];
+	return lines.join('\n');
+}
+
+/**
+ * Generate diagnostic tips based on trace analysis.
+ * Identifies common problems and suggests fixes.
+ * Returns an array of human-readable tips (empty if no issues found).
+ */
+export function diagnoseTrace(events: TraceEvent[], summary: TraceSummary): string[]
+{
+	const tips: string[] = [];
+	const {w1} = summary;
+
+	// Check for runtime errors
+	const errors = events.filter((e) => e.actor === 'W1' && e.type === 'ERROR');
+	if (errors.length > 0)
+	{
+		const firstErr = errors[0]!;
+		tips.push(`BOT ERROR: Your bot threw "${firstErr.detail}" on tick ${firstErr.tick}. The bot does nothing when it throws. Fix this first.`);
+		if (errors.length > 1) tips.push(`  (${errors.length} total errors — likely the same bug repeating every tick)`);
+	}
+
+	// Check for range warnings
+	const rangeWarnings = events.filter((e) => e.actor === 'W1' && e.type === 'WARNING' && e.detail.includes('range'));
+	if (rangeWarnings.length > 0)
+	{
+		tips.push(`RANGE: ${rangeWarnings.length} of your missiles had range shorter than target distance. Increase missile duration or get closer before firing.`);
+	}
+
+	// No missiles fired
+	if (w1.missilesLaunched === 0 && errors.length === 0)
+	{
+		tips.push('NO OFFENSE: Your bot fired 0 missiles. Check that you return missile() when useTicksUntilReady() === 0.');
+	}
+
+	// Very low hit rate
+	if (w1.missilesLaunched >= 3 && w1.hits === 0)
+	{
+		tips.push(`ACCURACY: Fired ${w1.missilesLaunched} missiles but 0 hit. Consider: more homing (higher turnRate), or use getLeadPosition() for straight missiles, or get closer.`);
+	}
+	else if (w1.missilesLaunched >= 5 && w1.hits / w1.missilesLaunched < 0.25)
+	{
+		tips.push(`LOW ACCURACY: Only ${((w1.hits / w1.missilesLaunched) * 100).toFixed(0)}% hit rate. Try increasing turnRate for more homing, or use getLeadPosition() for prediction.`);
+	}
+
+	// No shields against incoming damage
+	if (w1.damageReceived > 20 && w1.shields === 0)
+	{
+		tips.push(`NO DEFENSE: Took ${w1.damageReceived.toFixed(0)} damage with 0 shields. Use useThreats() to detect incoming missiles and shield() when you can't dodge.`);
+	}
+
+	// Too much idle time
+	if (summary.ticks > 500)
+	{
+		const idleMovements = w1.movement.still;
+		const totalMovements = idleMovements + w1.movement.approach + w1.movement.strafe + w1.movement.retreat;
+		if (totalMovements > 0 && idleMovements / totalMovements > 0.5)
+		{
+			tips.push(`IDLE: Your bot was stationary ${((idleMovements / totalMovements) * 100).toFixed(0)}% of the time. Move to dodge missiles and close distance.`);
+		}
+	}
+
+	return tips;
+}
+
+/** Format diagnostic tips as a human-readable string. */
+export function formatDiagnosis(tips: string[]): string
+{
+	if (tips.length === 0) return '';
+	const lines = ['  Diagnosis:'];
+	for (const tip of tips)
+	{
+		lines.push(`    - ${tip}`);
+	}
+	return lines.join('\n');
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function formatDodgeDetail(state: GameState, proj: ProjectileState, missileDistance: number, speed: number): string
+{
+	const angle = dodgeAngle(state.velocity, proj.rotation);
+	return `missile at ${missileDistance.toFixed(0)}u rot=${proj.rotation.toFixed(0)}° dodge_angle=${angle.toFixed(0)}° ` +
+		`spd=${speed.toFixed(2)} ${state.state}`;
+}
+
+function dodgeAngle(wizardVelocity: {x: number; y: number}, missileRotation: number): number
+{
+	const speed = Math.sqrt(wizardVelocity.x ** 2 + wizardVelocity.y ** 2);
+	if (speed < 0.01) return 0;
+	const missileRad = missileRotation * (Math.PI / 180);
+	const dot = Math.cos(missileRad) * (wizardVelocity.x / speed) + Math.sin(missileRad) * (wizardVelocity.y / speed);
+	return Math.acos(Math.max(-1, Math.min(1, Math.abs(dot)))) * (180 / Math.PI);
+}
+
+function actorFromId(ev: SimEvent): 'W1' | 'W2'
+{
+	if ('wizardId' in ev) return ev.wizardId === 'wizard-1' ? 'W1' : 'W2';
+	if ('ownerId' in ev) return ev.ownerId === 'wizard-1' ? 'W1' : 'W2';
+	return 'W1';
+}
+
+function classifyMovement(state: GameState, enemy: GameState['enemies'][0], speed: number): string
+{
+	if (speed < 0.1) return 'STILL';
+	const toEnemyAngle = Math.atan2(enemy.position.y - state.position.y, enemy.position.x - state.position.x);
+	const moveAngle = Math.atan2(state.velocity.y, state.velocity.x);
+	let angleDiff = ((moveAngle - toEnemyAngle) * 180 / Math.PI) % 360;
+	if (angleDiff > 180) angleDiff -= 360;
+	if (angleDiff < -180) angleDiff += 360;
+	const absAngle = Math.abs(angleDiff);
+	if (absAngle < 30) return 'APPROACH';
+	if (absAngle > 150) return 'RETREAT';
+	if (absAngle >= 60 && absAngle <= 120) return 'STRAFE';
+	if (absAngle < 60) return 'APPROACH+STRAFE';
+	return 'RETREAT+STRAFE';
+}