@vibemancer/core 0.1.0 → 0.1.1

package/src/engine/simulation.ts

@@ -1,828 +1,828 @@
-import {
-	GameState,
-	WizardState,
-	ProjectileState,
-	WizardFunction,
-	WizardActions,
-	MissileAIFunction,
-	MissileActions,
-	GameConfig,
-	MissileConfig,
-} from '../types.js';
-import {
-	ARENA_WIDTH,
-	ARENA_HEIGHT,
-	SPAWN_DISTANCE,
-	WIZARD_HEALTH,
-	TICKS_PER_SECOND,
-	calculateBlinkCooldown,
-	BLINK_RANGE,
-	WIZARD_RADIUS,
-	MATCH_DURATION,
-	validateMissileConfig,
-	calculateMissileRadius,
-	ARENA_WATER_BUFFER,
-} from '../rules.js';
-import {moveWizard, moveProjectile, sweptCircleCollision, clampToArena, resolveWizardCollision} from './physics.js';
-import {applyDamage, updateShield, startCast, completeCast} from './spells.js';
-import {runWithHooks, resetAllHooks, clearHooks} from './hooks-runtime.js';
-import {angleTo, normalizeAngle, angleDiff} from '../utils/angles.js';
-import {createRandom, createEntitySeed} from '../utils/random.js';
-
-export interface InternalWizardState extends WizardState
-{
-	missileConfig?: MissileConfig;
-	missileAI?: MissileAIFunction;
-	blinkTarget?: {x: number; y: number};
-	// Combat tracking
-	damageDealt: number;
-	damageTaken: number;
-	lastHitTick: number;
-}
-
-/**
- * Initialize a new match state.
- */
-export function createInitialState(_seed: number, spawnDist: number = SPAWN_DISTANCE): GameState
-{
-	const center = {x: ARENA_WIDTH / 2, y: ARENA_HEIGHT / 2};
-	const offset = spawnDist / 2;
-
-	const wizard1: WizardState = {
-		id: 'wizard-1',
-		position: {x: center.x - offset, y: center.y},
-		rotation: 0,
-		health: WIZARD_HEALTH,
-		maxHealth: WIZARD_HEALTH,
-		state: 'idle',
-		blinkCooldown: 0,
-		velocity: {x: 0, y: 0},
-	};
-
-	const wizard2: WizardState = {
-		id: 'wizard-2',
-		position: {x: center.x + offset, y: center.y},
-		rotation: 180,
-		health: WIZARD_HEALTH,
-		maxHealth: WIZARD_HEALTH,
-		state: 'idle',
-		blinkCooldown: 0,
-		velocity: {x: 0, y: 0},
-	};
-
-	return {
-		tick: 0,
-		position: wizard1.position,
-		rotation: wizard1.rotation,
-		health: wizard1.health,
-		maxHealth: wizard1.maxHealth,
-		state: wizard1.state,
-		blinkCooldown: wizard1.blinkCooldown,
-		velocity: wizard1.velocity,
-		enemies: [wizard2],
-		projectiles: [],
-		myProjectiles: [],
-		damageDealt: 0,
-		damageTaken: 0,
-		lastHitTick: 0,
-	};
-}
-
-/**
- * Process one game tick.
- */
-export function tick(
-	currentTick: number,
-	wizard1AI: WizardFunction,
-	wizard2AI: WizardFunction,
-	config: GameConfig,
-	wizards: InternalWizardState[],
-	projectiles: ProjectileState[],
-	missileAIs: Map<string, MissileAIFunction>,
-	matchSeed: number,
-): {
-	nextTick: number;
-	wizards: InternalWizardState[];
-	projectiles: ProjectileState[];
-	errors: BotError[];
-}
-{
-	const nextTick = currentTick + 1;
-	const errors: BotError[] = [];
-
-	// 1. Run wizard AIs with isolated random generators
-	// Each wizard gets a fresh random generator seeded by (matchSeed, wizardId, tick)
-	const random1 = createRandom(createEntitySeed(matchSeed, wizards[0]!.id, nextTick));
-	const random2 = createRandom(createEntitySeed(matchSeed, wizards[1]!.id, nextTick));
-
-	// Wrap AI calls in try-catch - if AI throws, wizard does nothing (Lesson #21)
-	let actions1: WizardActions = {move: {x: 0, y: 0}};
-	try
-	{
-		actions1 = runWithHooks(wizards[0]!.id, () => wizard1AI({
-			state: getPlayerStateView(0, wizards, projectiles, nextTick),
-			config,
-			random: random1,
-		})) ?? {move: {x: 0, y: 0}};
-	}
-	catch(e)
-	{
-		errors.push({tick: nextTick, entityId: 'wizard-1', message: e instanceof Error ? e.message : String(e)});
-	}
-
-	let actions2: WizardActions = {move: {x: 0, y: 0}};
-	try
-	{
-		actions2 = runWithHooks(wizards[1]!.id, () => wizard2AI({
-			state: getPlayerStateView(1, wizards, projectiles, nextTick),
-			config,
-			random: random2,
-		})) ?? {move: {x: 0, y: 0}};
-	}
-	catch(e)
-	{
-		errors.push({tick: nextTick, entityId: 'wizard-2', message: e instanceof Error ? e.message : String(e)});
-	}
-
-	const actions = [actions1, actions2];
-
-	// 2. Update wizards
-	wizards.forEach((wizard, i) =>
-	{
-		const action = actions[i]!;
-
-		// Handle cooldowns
-		if (wizard.blinkCooldown > 0)
-		{
-			wizard.blinkCooldown--;
-		}
-		if (wizard.state === 'gcd_locked' && wizard.gcdRemaining !== undefined)
-		{
-			wizard.gcdRemaining--;
-			if (wizard.gcdRemaining <= 0)
-			{
-				wizard.state = 'idle';
-				delete wizard.gcdRemaining;
-			}
-		}
-
-		// Auto-aim: face the enemy by default, bot can override with aimDirection
-		const enemy = wizards[1 - i]!;
-		if (action.aimDirection !== undefined && Number.isFinite(action.aimDirection))
-		{
-			wizard.rotation = action.aimDirection;
-		}
-		else
-		{
-			wizard.rotation = angleTo(wizard.position, enemy.position);
-		}
-
-		// Handle casting
-		if (wizard.state === 'casting' && wizard.castProgress !== undefined && wizard.castDuration !== undefined)
-		{
-			wizard.castProgress++;
-			if (wizard.castProgress >= wizard.castDuration)
-			{
-				const spell = wizard.castingSpell;
-
-				if (spell === 'missile' && wizard.missileConfig && wizard.missileAI)
-				{
-					// Validate missile config to enforce minimums (Lesson #9)
-					const validConfig = validateMissileConfig(wizard.missileConfig);
-					const id = `missile-${wizard.id}-${nextTick}`;
-					const projectile: ProjectileState = {
-						id,
-						type: 'missile',
-						ownerId: wizard.id,
-						position: {...wizard.position},
-						rotation: wizard.rotation, // Use wizard's rotation at time of firing
-						speed: validConfig.speed,
-						turnRate: validConfig.turnRate,
-						damage: validConfig.damage,
-						remainingTicks: validConfig.duration,
-					};
-					projectiles.push(projectile);
-					missileAIs.set(id, wizard.missileAI);
-					// Track last missile for warmup system
-					wizard.lastMissileConfig = {...validConfig};
-					delete wizard.missileConfig;
-					delete wizard.missileAI;
-				}
-				else if (spell === 'blink' && wizard.blinkTarget)
-				{
-					// Clamp blink target to BLINK_RANGE from current position
-					const dx = wizard.blinkTarget.x - wizard.position.x;
-					const dy = wizard.blinkTarget.y - wizard.position.y;
-					const distance = Math.sqrt(dx * dx + dy * dy);
-
-					let targetPos = wizard.blinkTarget;
-					if (distance > BLINK_RANGE)
-					{
-						// Clamp to max range in the same direction
-						const scale = BLINK_RANGE / distance;
-						targetPos = {
-							x: wizard.position.x + dx * scale,
-							y: wizard.position.y + dy * scale,
-						};
-					}
-
-					// Clamp to arena bounds and calculate actual distance traveled
-					const oldPos = wizard.position;
-					wizard.position = clampToArena(targetPos, WIZARD_RADIUS);
-					const actualDx = wizard.position.x - oldPos.x;
-					const actualDy = wizard.position.y - oldPos.y;
-					const actualDistance = Math.sqrt(actualDx * actualDx + actualDy * actualDy);
-					wizard.blinkCooldown = calculateBlinkCooldown(actualDistance);
-					delete wizard.blinkTarget;
-				}
-
-				completeCast(wizard);
-			}
-		}
-
-		// Handle movement (default to no movement if bot didn't provide move)
-		const oldPos = wizard.position;
-		const move = action.move ?? {x: 0, y: 0};
-		wizard.position = moveWizard(wizard, move, 1);
-		wizard.velocity = {
-			x: wizard.position.x - oldPos.x,
-			y: wizard.position.y - oldPos.y,
-		};
-
-		// Handle shield — cancel goes to idle (no GCD)
-		if (wizard.state === 'channeling')
-		{
-			updateShield(wizard, 1);
-			if (action.cancel)
-			{
-				wizard.state = 'idle';
-				delete wizard.channelingSpell;
-				delete wizard.channelDuration;
-			}
-		}
-
-		// Handle start cast
-		if (wizard.state === 'idle' && action.startCast)
-		{
-			if (action.startCast.spell === 'blink' && wizard.blinkCooldown > 0)
-			{
-				// Cannot blink yet
-			}
-			else
-			{
-				startCast(wizard, action.startCast.spell, action.startCast.spell === 'missile' ? action.startCast.config : undefined);
-				if (action.startCast.spell === 'missile')
-				{
-					wizard.missileConfig = action.startCast.config;
-					wizard.missileAI = action.startCast.missileAI;
-					if (action.startCast.direction !== undefined)
-					{
-						wizard.rotation = action.startCast.direction;
-					}
-				}
-				else if (action.startCast.spell === 'blink')
-				{
-					wizard.blinkTarget = action.startCast.target;
-				}
-			}
-		}
-
-		// Handle cancel
-		if (wizard.state === 'casting' && action.cancel)
-		{
-			wizard.state = 'idle';
-			delete wizard.castingSpell;
-			delete wizard.castProgress;
-			delete wizard.castDuration;
-			delete wizard.missileConfig;
-			delete wizard.missileAI;
-			delete wizard.blinkTarget;
-		}
-	});
-
-	// 2b. Resolve wizard body collision (push apart if overlapping)
-	resolveWizardCollision(wizards[0]!, wizards[1]!);
-
-	// 3. Update projectiles
-	const remainingProjectiles: ProjectileState[] = [];
-	projectiles.forEach((projectile) =>
-	{
-		const ai = missileAIs.get(projectile.id);
-		if (ai)
-		{
-			const ownerIndex = wizards.findIndex((w) => w.id === projectile.ownerId);
-			// Each missile gets its own isolated random generator
-			const missileRandom = createRandom(createEntitySeed(matchSeed, projectile.id, nextTick));
-
-			// Wrap missile AI in try-catch - if it throws, missile continues straight (Lesson #21)
-			let missileActions: MissileActions = {};
-			try
-			{
-				missileActions = runWithHooks(projectile.id, () => ai({
-					missileState: projectileView(projectile),
-					worldState: getPlayerStateView(ownerIndex, wizards, projectiles, nextTick),
-					random: missileRandom,
-				})) ?? {};
-			}
-			catch(e)
-			{
-				errors.push({tick: nextTick, entityId: projectile.id, message: e instanceof Error ? e.message : String(e)});
-			}
-
-			if (missileActions.turnToward)
-			{
-				const targetAngle = angleTo(projectile.position, missileActions.turnToward);
-				const diff = angleDiff(projectile.rotation, targetAngle);
-				// Negative turnRate = anti-homing (turns away from target)
-				const absTurnRate = Math.abs(projectile.turnRate);
-				const effectiveDiff = projectile.turnRate >= 0 ? diff : -diff;
-				const turn = Math.max(-absTurnRate, Math.min(absTurnRate, effectiveDiff));
-				projectile.rotation = normalizeAngle(projectile.rotation + turn);
-			}
-		}
-
-		const oldPos = projectile.position;
-		projectile.position = moveProjectile(projectile, 1);
-		projectile.remainingTicks--;
-
-		// Check collisions
-		let hit = false;
-		const missileRadius = calculateMissileRadius(projectile.damage);
-		wizards.forEach((wizard) =>
-		{
-			if (wizard.id !== projectile.ownerId && !hit)
-			{
-				if (sweptCircleCollision(oldPos, projectile.position, missileRadius, wizard.position, WIZARD_RADIUS))
-				{
-					const actualDamage = applyDamage(wizard, projectile.damage);
-					hit = true;
-
-					// Track damage for combat tracking hooks
-					wizard.damageTaken += actualDamage;
-					wizard.lastHitTick = nextTick;
-
-					// Find the owner and track their damage dealt
-					const owner = wizards.find((w) => w.id === projectile.ownerId);
-					if (owner)
-					{
-						owner.damageDealt += actualDamage;
-					}
-				}
-			}
-		});
-
-		// Check if projectile is beyond the water buffer
-		const isOutOfBounds =
-			projectile.position.x < -ARENA_WATER_BUFFER ||
-			projectile.position.x > ARENA_WIDTH + ARENA_WATER_BUFFER ||
-			projectile.position.y < -ARENA_WATER_BUFFER ||
-			projectile.position.y > ARENA_HEIGHT + ARENA_WATER_BUFFER;
-
-		if (!hit && projectile.remainingTicks > 0 && !isOutOfBounds)
-		{
-			remainingProjectiles.push(projectile);
-		}
-		else
-		{
-			missileAIs.delete(projectile.id);
-			clearHooks(projectile.id);
-		}
-	});
-
-	return {
-		nextTick,
-		wizards,
-		projectiles: remainingProjectiles,
-		errors,
-	};
-}
-
-/**
- * Deep clone a wizard state to prevent mutation.
- */
-function cloneWizard(wizard: WizardState): WizardState
-{
-	return {
-		id: wizard.id,
-		position: {...wizard.position},
-		rotation: wizard.rotation,
-		health: wizard.health,
-		maxHealth: wizard.maxHealth,
-		state: wizard.state,
-		castingSpell: wizard.castingSpell,
-		castProgress: wizard.castProgress,
-		castDuration: wizard.castDuration,
-		channelingSpell: wizard.channelingSpell,
-		channelDuration: wizard.channelDuration,
-		gcdRemaining: wizard.gcdRemaining,
-		blinkCooldown: wizard.blinkCooldown,
-		velocity: {...wizard.velocity},
-	};
-}
-
-/**
- * Deep clone a projectile state to prevent mutation.
- */
-function cloneProjectile(projectile: ProjectileState): ProjectileState
-{
-	return {
-		id: projectile.id,
-		type: projectile.type,
-		ownerId: projectile.ownerId,
-		position: {...projectile.position},
-		rotation: projectile.rotation,
-		speed: projectile.speed,
-		turnRate: projectile.turnRate,
-		damage: projectile.damage,
-		remainingTicks: projectile.remainingTicks,
-	};
-}
-
-/**
- * Get the game state from a specific player's perspective.
- * Returns a deep clone to prevent mutation of history entries.
- * Used for history recording where independent snapshots are needed.
- */
-export function getPlayerState(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number): GameState
-{
-	const me = wizards[playerIndex]!;
-	const enemies = wizards.filter((_, i) => i !== playerIndex).map(cloneWizard);
-	const clonedProjectiles = projectiles.map(cloneProjectile);
-
-	return {
-		tick,
-		position: {...me.position},
-		rotation: me.rotation,
-		health: me.health,
-		maxHealth: me.maxHealth,
-		state: me.state,
-		castingSpell: me.castingSpell,
-		castProgress: me.castProgress,
-		castDuration: me.castDuration,
-		channelingSpell: me.channelingSpell,
-		channelDuration: me.channelDuration,
-		gcdRemaining: me.gcdRemaining,
-		blinkCooldown: me.blinkCooldown,
-		velocity: {...me.velocity},
-		lastMissileConfig: me.lastMissileConfig ? {...me.lastMissileConfig} : undefined,
-		warmupMultiplier: me.warmupMultiplier,
-		enemies,
-		projectiles: clonedProjectiles,
-		myProjectiles: clonedProjectiles.filter((p) => p.ownerId === me.id),
-		// Combat tracking
-		damageDealt: me.damageDealt,
-		damageTaken: me.damageTaken,
-		lastHitTick: me.lastHitTick,
-	};
-}
-
-/**
- * Create a lightweight read-only view of a projectile.
- * Clones only the mutable sub-objects (position) to prevent
- * bot code from corrupting internal simulation state.
- * Scalar fields are safe since they're copied by value.
- */
-function projectileView(p: ProjectileState): ProjectileState
-{
-	return {
-		id: p.id,
-		type: p.type,
-		ownerId: p.ownerId,
-		position: {x: p.position.x, y: p.position.y},
-		rotation: p.rotation,
-		speed: p.speed,
-		turnRate: p.turnRate,
-		damage: p.damage,
-		remainingTicks: p.remainingTicks,
-	};
-}
-
-/**
- * Extract public WizardState fields from an InternalWizardState.
- * Clones position and velocity ({x,y} spreads) to prevent bot code
- * from mutating internal simulation state. Scalar fields are safe.
- */
-function extractWizardView(wizard: InternalWizardState): WizardState
-{
-	return {
-		id: wizard.id,
-		position: {x: wizard.position.x, y: wizard.position.y},
-		rotation: wizard.rotation,
-		health: wizard.health,
-		maxHealth: wizard.maxHealth,
-		state: wizard.state,
-		castingSpell: wizard.castingSpell,
-		castProgress: wizard.castProgress,
-		castDuration: wizard.castDuration,
-		channelingSpell: wizard.channelingSpell,
-		channelDuration: wizard.channelDuration,
-		gcdRemaining: wizard.gcdRemaining,
-		blinkCooldown: wizard.blinkCooldown,
-		velocity: {x: wizard.velocity.x, y: wizard.velocity.y},
-	};
-}
-
-/**
- * Get a lightweight read-only view of game state for AI calls.
- * Clones only the small mutable sub-objects (position, velocity as {x,y})
- * to prevent bot code from corrupting internal simulation state.
- * Scalar fields are copied by value and safe from mutation.
- *
- * This is much faster than getPlayerState() (which deep-clones everything)
- * because it only spreads the tiny {x,y} objects, not full deep clones.
- */
-function getPlayerStateView(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number): GameState
-{
-	const me = wizards[playerIndex]!;
-	const enemies = wizards.filter((_, i) => i !== playerIndex).map(extractWizardView);
-	const projViews = projectiles.map(projectileView);
-
-	return {
-		tick,
-		position: {x: me.position.x, y: me.position.y},
-		rotation: me.rotation,
-		health: me.health,
-		maxHealth: me.maxHealth,
-		state: me.state,
-		castingSpell: me.castingSpell,
-		castProgress: me.castProgress,
-		castDuration: me.castDuration,
-		channelingSpell: me.channelingSpell,
-		channelDuration: me.channelDuration,
-		gcdRemaining: me.gcdRemaining,
-		blinkCooldown: me.blinkCooldown,
-		velocity: {x: me.velocity.x, y: me.velocity.y},
-		lastMissileConfig: me.lastMissileConfig ? {...me.lastMissileConfig} : undefined,
-		warmupMultiplier: me.warmupMultiplier,
-		enemies,
-		projectiles: projViews,
-		myProjectiles: projViews.filter((p) => p.ownerId === me.id),
-		// Combat tracking
-		damageDealt: me.damageDealt,
-		damageTaken: me.damageTaken,
-		lastHitTick: me.lastHitTick,
-	};
-}
-
-/** Winner of a single match: a wizard ID, 'draw' (simultaneous kill), or null (timeout). */
-export type MatchWinner = 'wizard-1' | 'wizard-2' | 'draw' | null;
-
-/** Winner of a fight (aggregate): a wizard ID or 'draw'. Never null. */
-export type FightWinner = 'wizard-1' | 'wizard-2' | 'draw';
-
-/**
- * Result of a simulation.
- */
-/** A runtime error captured from a bot or missile AI function. */
-export interface BotError
-{
-	tick: number;
-	entityId: string;
-	message: string;
-}
-
-export interface SimulateResult
-{
-	/** 'wizard-1'/'wizard-2' = killed opponent, 'draw' = simultaneous kill, null = timeout */
-	winner: MatchWinner;
-	ticks: number;
-	finalState: GameState;
-	history: GameState[];
-	/** Runtime errors thrown by bot or missile AI functions (empty if no errors). */
-	errors: BotError[];
-}
-
-/**
- * Result of a fight (best-of-5 at different spawn distances).
- */
-export interface FightResult
-{
-	wizard1Wins: number;
-	wizard2Wins: number;
-	draws: number;
-	/** Winner of the fight: 'wizard-1', 'wizard-2', or 'draw' (never null) */
-	winner: FightWinner;
-	/**
-	 * Individual match results (one per spawn distance, non-swapped only).
-	 * Used for visual playback in the web viewer. Scoring includes both sides.
-	 */
-	matches: SimulateResult[];
-}
-
-/** Spawn distances for the 5 matches in a fight (creates butterfly effect variation) */
-export const FIGHT_SPAWN_DISTANCES = [500, 550, 600, 650, 700];
-
-/**
- * Run a fight: 10 matches (5 spawn distances × 2 sides) between two bots.
- * Each spawn distance is played twice — once with each bot on each side —
- * to ensure results are independent of starting position.
- *
- * The `matches` array contains only the 5 non-swapped matches (for visual playback).
- * The scoring aggregates (wizard1Wins, wizard2Wins, draws) include all 10 matches.
- *
- * This is the standard way to determine who wins a matchup.
- * Used by both the tournament system and the visual UI.
- */
-export function fight(
-	wizard1AI: WizardFunction,
-	wizard2AI: WizardFunction,
-	options: {
-		seed?: number;
-		maxTicks?: number;
-	} = {},
-): FightResult
-{
-	const matches: SimulateResult[] = [];
-	let wizard1Wins = 0;
-	let wizard2Wins = 0;
-	let draws = 0;
-
-	for (const spawnDistance of FIGHT_SPAWN_DISTANCES)
-	{
-		// Normal side: wizard1 on left, wizard2 on right
-		const result = simulate(wizard1AI, wizard2AI, {
-			seed: options.seed,
-			maxTicks: options.maxTicks,
-			spawnDistance,
-		});
-
-		matches.push(result);
-
-		if (result.winner === 'wizard-1')
-		{
-			wizard1Wins++;
-		}
-		else if (result.winner === 'wizard-2')
-		{
-			wizard2Wins++;
-		}
-		else
-		{
-			draws++;
-		}
-
-		// Swapped side: wizard2 on left, wizard1 on right
-		// skipHistory: swapped matches are only for scoring, not visual playback
-		const swapped = simulate(wizard2AI, wizard1AI, {
-			seed: options.seed,
-			maxTicks: options.maxTicks,
-			spawnDistance,
-			skipHistory: true,
-		});
-
-		// Don't push swapped match to matches array (it's only for scoring)
-		if (swapped.winner === 'wizard-1')
-		{
-			// wizard-1 in swapped match = wizard2 from original perspective
-			wizard2Wins++;
-		}
-		else if (swapped.winner === 'wizard-2')
-		{
-			wizard1Wins++;
-		}
-		else
-		{
-			draws++;
-		}
-	}
-
-	const winner: FightWinner = wizard1Wins > wizard2Wins ? 'wizard-1'
-		: wizard2Wins > wizard1Wins ? 'wizard-2'
-			: 'draw';
-
-	return {wizard1Wins, wizard2Wins, draws, winner, matches};
-}
-
-/**
- * Run a full match simulation.
- *
- * @param options.skipHistory - When true, skips recording per-tick history snapshots.
- *   This dramatically improves performance (no deep cloning per tick) and is used
- *   by the optimizer and fight() scoring. The returned history array will be empty
- *   and finalState will still be populated.
- */
-export function simulate(
-	wizard1AI: WizardFunction,
-	wizard2AI: WizardFunction,
-	options: {
-		maxTicks?: number;
-		seed?: number;
-		spawnDistance?: number;
-		skipHistory?: boolean;
-	} = {},
-): SimulateResult
-{
-	// Validate AI functions (Lesson #1)
-	if (typeof wizard1AI !== 'function')
-	{
-		throw new Error('wizard1AI must be a function');
-	}
-	if (typeof wizard2AI !== 'function')
-	{
-		throw new Error('wizard2AI must be a function');
-	}
-
-	// Sanitize options (Lesson #3)
-	const {maxTicks: rawMaxTicks = MATCH_DURATION, seed: rawSeed = Date.now(), spawnDistance: rawSpawnDistance, skipHistory = false} = options;
-
-	// Sanitize seed - ensure valid 32-bit integer
-	const seed = Number.isFinite(rawSeed) ? Math.floor(rawSeed) & 0x7FFFFFFF : Date.now() & 0x7FFFFFFF;
-
-	// Sanitize maxTicks - ensure positive integer with reasonable limit
-	const maxTicks = Number.isFinite(rawMaxTicks) && rawMaxTicks > 0
-		? Math.min(Math.floor(rawMaxTicks), 100000) // Cap at 100k ticks (~16 min)
-		: MATCH_DURATION;
-
-	// Sanitize spawnDistance - must be positive and fit in arena
-	const spawnDistance = Number.isFinite(rawSpawnDistance) && rawSpawnDistance! > 0
-		? Math.min(rawSpawnDistance!, Math.min(ARENA_WIDTH, ARENA_HEIGHT) - 100) // Leave room for wizards
-		: SPAWN_DISTANCE;
-
-	const config: GameConfig = Object.freeze({
-		arenaSize: Object.freeze({width: ARENA_WIDTH, height: ARENA_HEIGHT}),
-		tickRate: TICKS_PER_SECOND,
-		maxTicks,
-	});
-
-	resetAllHooks();
-
-	const initialState = createInitialState(seed, spawnDistance);
-	const history: GameState[] = skipHistory ? [] : [initialState];
-	let currentTick = 0;
-	let wizards: InternalWizardState[] = [
-		{
-			id: 'wizard-1',
-			position: {x: ARENA_WIDTH / 2 - spawnDistance / 2, y: ARENA_HEIGHT / 2},
-			rotation: 0,
-			health: WIZARD_HEALTH,
-			maxHealth: WIZARD_HEALTH,
-			state: 'idle',
-			blinkCooldown: 0,
-			velocity: {x: 0, y: 0},
-			damageDealt: 0,
-			damageTaken: 0,
-			lastHitTick: 0,
-		},
-		{
-			id: 'wizard-2',
-			position: {x: ARENA_WIDTH / 2 + spawnDistance / 2, y: ARENA_HEIGHT / 2},
-			rotation: 180,
-			health: WIZARD_HEALTH,
-			maxHealth: WIZARD_HEALTH,
-			state: 'idle',
-			blinkCooldown: 0,
-			velocity: {x: 0, y: 0},
-			damageDealt: 0,
-			damageTaken: 0,
-			lastHitTick: 0,
-		},
-	];
-	let projectiles: ProjectileState[] = [];
-	const missileAIs = new Map<string, MissileAIFunction>();
-	const allErrors: BotError[] = [];
-
-	while (currentTick < maxTicks)
-	{
-		const result = tick(currentTick, wizard1AI, wizard2AI, config, wizards, projectiles, missileAIs, seed);
-		currentTick = result.nextTick;
-		wizards = result.wizards;
-		projectiles = result.projectiles;
-		if (result.errors.length > 0) allErrors.push(...result.errors);
-
-		if (!skipHistory)
-		{
-			// Deep-clone snapshot for history (needed for replay)
-			history.push(getPlayerState(0, wizards, projectiles, currentTick));
-		}
-
-		if (wizards[0]!.health <= 0 || wizards[1]!.health <= 0)
-		{
-			break;
-		}
-	}
-
-	let winner: MatchWinner = null;
-	if (wizards[0]!.health <= 0 && wizards[1]!.health <= 0)
-	{
-		winner = 'draw';
-	}
-	else if (wizards[1]!.health <= 0)
-	{
-		winner = 'wizard-1';
-	}
-	else if (wizards[0]!.health <= 0)
-	{
-		winner = 'wizard-2';
-	}
-
-	// Always create final state snapshot (needed for result)
-	const finalState = getPlayerState(0, wizards, projectiles, currentTick);
-
-	return {
-		winner,
-		ticks: currentTick,
-		finalState,
-		history: skipHistory ? [] : history,
-		errors: allErrors,
-	};
-}
+import {
+	GameState,
+	WizardState,
+	ProjectileState,
+	WizardFunction,
+	WizardActions,
+	MissileAIFunction,
+	MissileActions,
+	GameConfig,
+	MissileConfig,
+} from '../types.js';
+import {
+	ARENA_WIDTH,
+	ARENA_HEIGHT,
+	SPAWN_DISTANCE,
+	WIZARD_HEALTH,
+	TICKS_PER_SECOND,
+	calculateBlinkCooldown,
+	BLINK_RANGE,
+	WIZARD_RADIUS,
+	MATCH_DURATION,
+	validateMissileConfig,
+	calculateMissileRadius,
+	ARENA_WATER_BUFFER,
+} from '../rules.js';
+import {moveWizard, moveProjectile, sweptCircleCollision, clampToArena, resolveWizardCollision} from './physics.js';
+import {applyDamage, updateShield, startCast, completeCast} from './spells.js';
+import {runWithHooks, resetAllHooks, clearHooks} from './hooks-runtime.js';
+import {angleTo, normalizeAngle, angleDiff} from '../utils/angles.js';
+import {createRandom, createEntitySeed} from '../utils/random.js';
+
+export interface InternalWizardState extends WizardState
+{
+	missileConfig?: MissileConfig;
+	missileAI?: MissileAIFunction;
+	blinkTarget?: {x: number; y: number};
+	// Combat tracking
+	damageDealt: number;
+	damageTaken: number;
+	lastHitTick: number;
+}
+
+/**
+ * Initialize a new match state.
+ */
+export function createInitialState(_seed: number, spawnDist: number = SPAWN_DISTANCE): GameState
+{
+	const center = {x: ARENA_WIDTH / 2, y: ARENA_HEIGHT / 2};
+	const offset = spawnDist / 2;
+
+	const wizard1: WizardState = {
+		id: 'wizard-1',
+		position: {x: center.x - offset, y: center.y},
+		rotation: 0,
+		health: WIZARD_HEALTH,
+		maxHealth: WIZARD_HEALTH,
+		state: 'idle',
+		blinkCooldown: 0,
+		velocity: {x: 0, y: 0},
+	};
+
+	const wizard2: WizardState = {
+		id: 'wizard-2',
+		position: {x: center.x + offset, y: center.y},
+		rotation: 180,
+		health: WIZARD_HEALTH,
+		maxHealth: WIZARD_HEALTH,
+		state: 'idle',
+		blinkCooldown: 0,
+		velocity: {x: 0, y: 0},
+	};
+
+	return {
+		tick: 0,
+		position: wizard1.position,
+		rotation: wizard1.rotation,
+		health: wizard1.health,
+		maxHealth: wizard1.maxHealth,
+		state: wizard1.state,
+		blinkCooldown: wizard1.blinkCooldown,
+		velocity: wizard1.velocity,
+		enemies: [wizard2],
+		projectiles: [],
+		myProjectiles: [],
+		damageDealt: 0,
+		damageTaken: 0,
+		lastHitTick: 0,
+	};
+}
+
+/**
+ * Process one game tick.
+ */
+export function tick(
+	currentTick: number,
+	wizard1AI: WizardFunction,
+	wizard2AI: WizardFunction,
+	config: GameConfig,
+	wizards: InternalWizardState[],
+	projectiles: ProjectileState[],
+	missileAIs: Map<string, MissileAIFunction>,
+	matchSeed: number,
+): {
+	nextTick: number;
+	wizards: InternalWizardState[];
+	projectiles: ProjectileState[];
+	errors: BotError[];
+}
+{
+	const nextTick = currentTick + 1;
+	const errors: BotError[] = [];
+
+	// 1. Run wizard AIs with isolated random generators
+	// Each wizard gets a fresh random generator seeded by (matchSeed, wizardId, tick)
+	const random1 = createRandom(createEntitySeed(matchSeed, wizards[0]!.id, nextTick));
+	const random2 = createRandom(createEntitySeed(matchSeed, wizards[1]!.id, nextTick));
+
+	// Wrap AI calls in try-catch - if AI throws, wizard does nothing (Lesson #21)
+	let actions1: WizardActions = {move: {x: 0, y: 0}};
+	try
+	{
+		actions1 = runWithHooks(wizards[0]!.id, () => wizard1AI({
+			state: getPlayerStateView(0, wizards, projectiles, nextTick),
+			config,
+			random: random1,
+		})) ?? {move: {x: 0, y: 0}};
+	}
+	catch(e)
+	{
+		errors.push({tick: nextTick, entityId: 'wizard-1', message: e instanceof Error ? e.message : String(e)});
+	}
+
+	let actions2: WizardActions = {move: {x: 0, y: 0}};
+	try
+	{
+		actions2 = runWithHooks(wizards[1]!.id, () => wizard2AI({
+			state: getPlayerStateView(1, wizards, projectiles, nextTick),
+			config,
+			random: random2,
+		})) ?? {move: {x: 0, y: 0}};
+	}
+	catch(e)
+	{
+		errors.push({tick: nextTick, entityId: 'wizard-2', message: e instanceof Error ? e.message : String(e)});
+	}
+
+	const actions = [actions1, actions2];
+
+	// 2. Update wizards
+	wizards.forEach((wizard, i) =>
+	{
+		const action = actions[i]!;
+
+		// Handle cooldowns
+		if (wizard.blinkCooldown > 0)
+		{
+			wizard.blinkCooldown--;
+		}
+		if (wizard.state === 'gcd_locked' && wizard.gcdRemaining !== undefined)
+		{
+			wizard.gcdRemaining--;
+			if (wizard.gcdRemaining <= 0)
+			{
+				wizard.state = 'idle';
+				delete wizard.gcdRemaining;
+			}
+		}
+
+		// Auto-aim: face the enemy by default, bot can override with aimDirection
+		const enemy = wizards[1 - i]!;
+		if (action.aimDirection !== undefined && Number.isFinite(action.aimDirection))
+		{
+			wizard.rotation = action.aimDirection;
+		}
+		else
+		{
+			wizard.rotation = angleTo(wizard.position, enemy.position);
+		}
+
+		// Handle casting
+		if (wizard.state === 'casting' && wizard.castProgress !== undefined && wizard.castDuration !== undefined)
+		{
+			wizard.castProgress++;
+			if (wizard.castProgress >= wizard.castDuration)
+			{
+				const spell = wizard.castingSpell;
+
+				if (spell === 'missile' && wizard.missileConfig && wizard.missileAI)
+				{
+					// Validate missile config to enforce minimums (Lesson #9)
+					const validConfig = validateMissileConfig(wizard.missileConfig);
+					const id = `missile-${wizard.id}-${nextTick}`;
+					const projectile: ProjectileState = {
+						id,
+						type: 'missile',
+						ownerId: wizard.id,
+						position: {...wizard.position},
+						rotation: wizard.rotation, // Use wizard's rotation at time of firing
+						speed: validConfig.speed,
+						turnRate: validConfig.turnRate,
+						damage: validConfig.damage,
+						remainingTicks: validConfig.duration,
+					};
+					projectiles.push(projectile);
+					missileAIs.set(id, wizard.missileAI);
+					// Track last missile for warmup system
+					wizard.lastMissileConfig = {...validConfig};
+					delete wizard.missileConfig;
+					delete wizard.missileAI;
+				}
+				else if (spell === 'blink' && wizard.blinkTarget)
+				{
+					// Clamp blink target to BLINK_RANGE from current position
+					const dx = wizard.blinkTarget.x - wizard.position.x;
+					const dy = wizard.blinkTarget.y - wizard.position.y;
+					const distance = Math.sqrt(dx * dx + dy * dy);
+
+					let targetPos = wizard.blinkTarget;
+					if (distance > BLINK_RANGE)
+					{
+						// Clamp to max range in the same direction
+						const scale = BLINK_RANGE / distance;
+						targetPos = {
+							x: wizard.position.x + dx * scale,
+							y: wizard.position.y + dy * scale,
+						};
+					}
+
+					// Clamp to arena bounds and calculate actual distance traveled
+					const oldPos = wizard.position;
+					wizard.position = clampToArena(targetPos, WIZARD_RADIUS);
+					const actualDx = wizard.position.x - oldPos.x;
+					const actualDy = wizard.position.y - oldPos.y;
+					const actualDistance = Math.sqrt(actualDx * actualDx + actualDy * actualDy);
+					wizard.blinkCooldown = calculateBlinkCooldown(actualDistance);
+					delete wizard.blinkTarget;
+				}
+
+				completeCast(wizard);
+			}
+		}
+
+		// Handle movement (default to no movement if bot didn't provide move)
+		const oldPos = wizard.position;
+		const move = action.move ?? {x: 0, y: 0};
+		wizard.position = moveWizard(wizard, move, 1);
+		wizard.velocity = {
+			x: wizard.position.x - oldPos.x,
+			y: wizard.position.y - oldPos.y,
+		};
+
+		// Handle shield — cancel goes to idle (no GCD)
+		if (wizard.state === 'channeling')
+		{
+			updateShield(wizard, 1);
+			if (action.cancel)
+			{
+				wizard.state = 'idle';
+				delete wizard.channelingSpell;
+				delete wizard.channelDuration;
+			}
+		}
+
+		// Handle start cast
+		if (wizard.state === 'idle' && action.startCast)
+		{
+			if (action.startCast.spell === 'blink' && wizard.blinkCooldown > 0)
+			{
+				// Cannot blink yet
+			}
+			else
+			{
+				startCast(wizard, action.startCast.spell, action.startCast.spell === 'missile' ? action.startCast.config : undefined);
+				if (action.startCast.spell === 'missile')
+				{
+					wizard.missileConfig = action.startCast.config;
+					wizard.missileAI = action.startCast.missileAI;
+					if (action.startCast.direction !== undefined)
+					{
+						wizard.rotation = action.startCast.direction;
+					}
+				}
+				else if (action.startCast.spell === 'blink')
+				{
+					wizard.blinkTarget = action.startCast.target;
+				}
+			}
+		}
+
+		// Handle cancel
+		if (wizard.state === 'casting' && action.cancel)
+		{
+			wizard.state = 'idle';
+			delete wizard.castingSpell;
+			delete wizard.castProgress;
+			delete wizard.castDuration;
+			delete wizard.missileConfig;
+			delete wizard.missileAI;
+			delete wizard.blinkTarget;
+		}
+	});
+
+	// 2b. Resolve wizard body collision (push apart if overlapping)
+	resolveWizardCollision(wizards[0]!, wizards[1]!);
+
+	// 3. Update projectiles
+	const remainingProjectiles: ProjectileState[] = [];
+	projectiles.forEach((projectile) =>
+	{
+		const ai = missileAIs.get(projectile.id);
+		if (ai)
+		{
+			const ownerIndex = wizards.findIndex((w) => w.id === projectile.ownerId);
+			// Each missile gets its own isolated random generator
+			const missileRandom = createRandom(createEntitySeed(matchSeed, projectile.id, nextTick));
+
+			// Wrap missile AI in try-catch - if it throws, missile continues straight (Lesson #21)
+			let missileActions: MissileActions = {};
+			try
+			{
+				missileActions = runWithHooks(projectile.id, () => ai({
+					missileState: projectileView(projectile),
+					worldState: getPlayerStateView(ownerIndex, wizards, projectiles, nextTick),
+					random: missileRandom,
+				})) ?? {};
+			}
+			catch(e)
+			{
+				errors.push({tick: nextTick, entityId: projectile.id, message: e instanceof Error ? e.message : String(e)});
+			}
+
+			if (missileActions.turnToward)
+			{
+				const targetAngle = angleTo(projectile.position, missileActions.turnToward);
+				const diff = angleDiff(projectile.rotation, targetAngle);
+				// Negative turnRate = anti-homing (turns away from target)
+				const absTurnRate = Math.abs(projectile.turnRate);
+				const effectiveDiff = projectile.turnRate >= 0 ? diff : -diff;
+				const turn = Math.max(-absTurnRate, Math.min(absTurnRate, effectiveDiff));
+				projectile.rotation = normalizeAngle(projectile.rotation + turn);
+			}
+		}
+
+		const oldPos = projectile.position;
+		projectile.position = moveProjectile(projectile, 1);
+		projectile.remainingTicks--;
+
+		// Check collisions
+		let hit = false;
+		const missileRadius = calculateMissileRadius(projectile.damage);
+		wizards.forEach((wizard) =>
+		{
+			if (wizard.id !== projectile.ownerId && !hit)
+			{
+				if (sweptCircleCollision(oldPos, projectile.position, missileRadius, wizard.position, WIZARD_RADIUS))
+				{
+					const actualDamage = applyDamage(wizard, projectile.damage);
+					hit = true;
+
+					// Track damage for combat tracking hooks
+					wizard.damageTaken += actualDamage;
+					wizard.lastHitTick = nextTick;
+
+					// Find the owner and track their damage dealt
+					const owner = wizards.find((w) => w.id === projectile.ownerId);
+					if (owner)
+					{
+						owner.damageDealt += actualDamage;
+					}
+				}
+			}
+		});
+
+		// Check if projectile is beyond the water buffer
+		const isOutOfBounds =
+			projectile.position.x < -ARENA_WATER_BUFFER ||
+			projectile.position.x > ARENA_WIDTH + ARENA_WATER_BUFFER ||
+			projectile.position.y < -ARENA_WATER_BUFFER ||
+			projectile.position.y > ARENA_HEIGHT + ARENA_WATER_BUFFER;
+
+		if (!hit && projectile.remainingTicks > 0 && !isOutOfBounds)
+		{
+			remainingProjectiles.push(projectile);
+		}
+		else
+		{
+			missileAIs.delete(projectile.id);
+			clearHooks(projectile.id);
+		}
+	});
+
+	return {
+		nextTick,
+		wizards,
+		projectiles: remainingProjectiles,
+		errors,
+	};
+}
+
+/**
+ * Deep clone a wizard state to prevent mutation.
+ */
+function cloneWizard(wizard: WizardState): WizardState
+{
+	return {
+		id: wizard.id,
+		position: {...wizard.position},
+		rotation: wizard.rotation,
+		health: wizard.health,
+		maxHealth: wizard.maxHealth,
+		state: wizard.state,
+		castingSpell: wizard.castingSpell,
+		castProgress: wizard.castProgress,
+		castDuration: wizard.castDuration,
+		channelingSpell: wizard.channelingSpell,
+		channelDuration: wizard.channelDuration,
+		gcdRemaining: wizard.gcdRemaining,
+		blinkCooldown: wizard.blinkCooldown,
+		velocity: {...wizard.velocity},
+	};
+}
+
+/**
+ * Deep clone a projectile state to prevent mutation.
+ */
+function cloneProjectile(projectile: ProjectileState): ProjectileState
+{
+	return {
+		id: projectile.id,
+		type: projectile.type,
+		ownerId: projectile.ownerId,
+		position: {...projectile.position},
+		rotation: projectile.rotation,
+		speed: projectile.speed,
+		turnRate: projectile.turnRate,
+		damage: projectile.damage,
+		remainingTicks: projectile.remainingTicks,
+	};
+}
+
+/**
+ * Get the game state from a specific player's perspective.
+ * Returns a deep clone to prevent mutation of history entries.
+ * Used for history recording where independent snapshots are needed.
+ */
+export function getPlayerState(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number): GameState
+{
+	const me = wizards[playerIndex]!;
+	const enemies = wizards.filter((_, i) => i !== playerIndex).map(cloneWizard);
+	const clonedProjectiles = projectiles.map(cloneProjectile);
+
+	return {
+		tick,
+		position: {...me.position},
+		rotation: me.rotation,
+		health: me.health,
+		maxHealth: me.maxHealth,
+		state: me.state,
+		castingSpell: me.castingSpell,
+		castProgress: me.castProgress,
+		castDuration: me.castDuration,
+		channelingSpell: me.channelingSpell,
+		channelDuration: me.channelDuration,
+		gcdRemaining: me.gcdRemaining,
+		blinkCooldown: me.blinkCooldown,
+		velocity: {...me.velocity},
+		lastMissileConfig: me.lastMissileConfig ? {...me.lastMissileConfig} : undefined,
+		warmupMultiplier: me.warmupMultiplier,
+		enemies,
+		projectiles: clonedProjectiles,
+		myProjectiles: clonedProjectiles.filter((p) => p.ownerId === me.id),
+		// Combat tracking
+		damageDealt: me.damageDealt,
+		damageTaken: me.damageTaken,
+		lastHitTick: me.lastHitTick,
+	};
+}
+
+/**
+ * Create a lightweight read-only view of a projectile.
+ * Clones only the mutable sub-objects (position) to prevent
+ * bot code from corrupting internal simulation state.
+ * Scalar fields are safe since they're copied by value.
+ */
+function projectileView(p: ProjectileState): ProjectileState
+{
+	return {
+		id: p.id,
+		type: p.type,
+		ownerId: p.ownerId,
+		position: {x: p.position.x, y: p.position.y},
+		rotation: p.rotation,
+		speed: p.speed,
+		turnRate: p.turnRate,
+		damage: p.damage,
+		remainingTicks: p.remainingTicks,
+	};
+}
+
+/**
+ * Extract public WizardState fields from an InternalWizardState.
+ * Clones position and velocity ({x,y} spreads) to prevent bot code
+ * from mutating internal simulation state. Scalar fields are safe.
+ */
+function extractWizardView(wizard: InternalWizardState): WizardState
+{
+	return {
+		id: wizard.id,
+		position: {x: wizard.position.x, y: wizard.position.y},
+		rotation: wizard.rotation,
+		health: wizard.health,
+		maxHealth: wizard.maxHealth,
+		state: wizard.state,
+		castingSpell: wizard.castingSpell,
+		castProgress: wizard.castProgress,
+		castDuration: wizard.castDuration,
+		channelingSpell: wizard.channelingSpell,
+		channelDuration: wizard.channelDuration,
+		gcdRemaining: wizard.gcdRemaining,
+		blinkCooldown: wizard.blinkCooldown,
+		velocity: {x: wizard.velocity.x, y: wizard.velocity.y},
+	};
+}
+
+/**
+ * Get a lightweight read-only view of game state for AI calls.
+ * Clones only the small mutable sub-objects (position, velocity as {x,y})
+ * to prevent bot code from corrupting internal simulation state.
+ * Scalar fields are copied by value and safe from mutation.
+ *
+ * This is much faster than getPlayerState() (which deep-clones everything)
+ * because it only spreads the tiny {x,y} objects, not full deep clones.
+ */
+function getPlayerStateView(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number): GameState
+{
+	const me = wizards[playerIndex]!;
+	const enemies = wizards.filter((_, i) => i !== playerIndex).map(extractWizardView);
+	const projViews = projectiles.map(projectileView);
+
+	return {
+		tick,
+		position: {x: me.position.x, y: me.position.y},
+		rotation: me.rotation,
+		health: me.health,
+		maxHealth: me.maxHealth,
+		state: me.state,
+		castingSpell: me.castingSpell,
+		castProgress: me.castProgress,
+		castDuration: me.castDuration,
+		channelingSpell: me.channelingSpell,
+		channelDuration: me.channelDuration,
+		gcdRemaining: me.gcdRemaining,
+		blinkCooldown: me.blinkCooldown,
+		velocity: {x: me.velocity.x, y: me.velocity.y},
+		lastMissileConfig: me.lastMissileConfig ? {...me.lastMissileConfig} : undefined,
+		warmupMultiplier: me.warmupMultiplier,
+		enemies,
+		projectiles: projViews,
+		myProjectiles: projViews.filter((p) => p.ownerId === me.id),
+		// Combat tracking
+		damageDealt: me.damageDealt,
+		damageTaken: me.damageTaken,
+		lastHitTick: me.lastHitTick,
+	};
+}
+
+/** Winner of a single match: a wizard ID, 'draw' (simultaneous kill), or null (timeout). */
+export type MatchWinner = 'wizard-1' | 'wizard-2' | 'draw' | null;
+
+/** Winner of a fight (aggregate): a wizard ID or 'draw'. Never null. */
+export type FightWinner = 'wizard-1' | 'wizard-2' | 'draw';
+
+/**
+ * Result of a simulation.
+ */
+/** A runtime error captured from a bot or missile AI function. */
+export interface BotError
+{
+	tick: number;
+	entityId: string;
+	message: string;
+}
+
+export interface SimulateResult
+{
+	/** 'wizard-1'/'wizard-2' = killed opponent, 'draw' = simultaneous kill, null = timeout */
+	winner: MatchWinner;
+	ticks: number;
+	finalState: GameState;
+	history: GameState[];
+	/** Runtime errors thrown by bot or missile AI functions (empty if no errors). */
+	errors: BotError[];
+}
+
+/**
+ * Result of a fight (best-of-5 at different spawn distances).
+ */
+export interface FightResult
+{
+	wizard1Wins: number;
+	wizard2Wins: number;
+	draws: number;
+	/** Winner of the fight: 'wizard-1', 'wizard-2', or 'draw' (never null) */
+	winner: FightWinner;
+	/**
+	 * Individual match results (one per spawn distance, non-swapped only).
+	 * Used for visual playback in the web viewer. Scoring includes both sides.
+	 */
+	matches: SimulateResult[];
+}
+
+/** Spawn distances for the 5 matches in a fight (creates butterfly effect variation) */
+export const FIGHT_SPAWN_DISTANCES = [500, 550, 600, 650, 700];
+
+/**
+ * Run a fight: 10 matches (5 spawn distances × 2 sides) between two bots.
+ * Each spawn distance is played twice — once with each bot on each side —
+ * to ensure results are independent of starting position.
+ *
+ * The `matches` array contains only the 5 non-swapped matches (for visual playback).
+ * The scoring aggregates (wizard1Wins, wizard2Wins, draws) include all 10 matches.
+ *
+ * This is the standard way to determine who wins a matchup.
+ * Used by both the tournament system and the visual UI.
+ */
+export function fight(
+	wizard1AI: WizardFunction,
+	wizard2AI: WizardFunction,
+	options: {
+		seed?: number;
+		maxTicks?: number;
+	} = {},
+): FightResult
+{
+	const matches: SimulateResult[] = [];
+	let wizard1Wins = 0;
+	let wizard2Wins = 0;
+	let draws = 0;
+
+	for (const spawnDistance of FIGHT_SPAWN_DISTANCES)
+	{
+		// Normal side: wizard1 on left, wizard2 on right
+		const result = simulate(wizard1AI, wizard2AI, {
+			seed: options.seed,
+			maxTicks: options.maxTicks,
+			spawnDistance,
+		});
+
+		matches.push(result);
+
+		if (result.winner === 'wizard-1')
+		{
+			wizard1Wins++;
+		}
+		else if (result.winner === 'wizard-2')
+		{
+			wizard2Wins++;
+		}
+		else
+		{
+			draws++;
+		}
+
+		// Swapped side: wizard2 on left, wizard1 on right
+		// skipHistory: swapped matches are only for scoring, not visual playback
+		const swapped = simulate(wizard2AI, wizard1AI, {
+			seed: options.seed,
+			maxTicks: options.maxTicks,
+			spawnDistance,
+			skipHistory: true,
+		});
+
+		// Don't push swapped match to matches array (it's only for scoring)
+		if (swapped.winner === 'wizard-1')
+		{
+			// wizard-1 in swapped match = wizard2 from original perspective
+			wizard2Wins++;
+		}
+		else if (swapped.winner === 'wizard-2')
+		{
+			wizard1Wins++;
+		}
+		else
+		{
+			draws++;
+		}
+	}
+
+	const winner: FightWinner = wizard1Wins > wizard2Wins ? 'wizard-1'
+		: wizard2Wins > wizard1Wins ? 'wizard-2'
+			: 'draw';
+
+	return {wizard1Wins, wizard2Wins, draws, winner, matches};
+}
+
+/**
+ * Run a full match simulation.
+ *
+ * @param options.skipHistory - When true, skips recording per-tick history snapshots.
+ *   This dramatically improves performance (no deep cloning per tick) and is used
+ *   by the optimizer and fight() scoring. The returned history array will be empty
+ *   and finalState will still be populated.
+ */
+export function simulate(
+	wizard1AI: WizardFunction,
+	wizard2AI: WizardFunction,
+	options: {
+		maxTicks?: number;
+		seed?: number;
+		spawnDistance?: number;
+		skipHistory?: boolean;
+	} = {},
+): SimulateResult
+{
+	// Validate AI functions (Lesson #1)
+	if (typeof wizard1AI !== 'function')
+	{
+		throw new Error('wizard1AI must be a function');
+	}
+	if (typeof wizard2AI !== 'function')
+	{
+		throw new Error('wizard2AI must be a function');
+	}
+
+	// Sanitize options (Lesson #3)
+	const {maxTicks: rawMaxTicks = MATCH_DURATION, seed: rawSeed = Date.now(), spawnDistance: rawSpawnDistance, skipHistory = false} = options;
+
+	// Sanitize seed - ensure valid 32-bit integer
+	const seed = Number.isFinite(rawSeed) ? Math.floor(rawSeed) & 0x7FFFFFFF : Date.now() & 0x7FFFFFFF;
+
+	// Sanitize maxTicks - ensure positive integer with reasonable limit
+	const maxTicks = Number.isFinite(rawMaxTicks) && rawMaxTicks > 0
+		? Math.min(Math.floor(rawMaxTicks), 100000) // Cap at 100k ticks (~16 min)
+		: MATCH_DURATION;
+
+	// Sanitize spawnDistance - must be positive and fit in arena
+	const spawnDistance = Number.isFinite(rawSpawnDistance) && rawSpawnDistance! > 0
+		? Math.min(rawSpawnDistance!, Math.min(ARENA_WIDTH, ARENA_HEIGHT) - 100) // Leave room for wizards
+		: SPAWN_DISTANCE;
+
+	const config: GameConfig = Object.freeze({
+		arenaSize: Object.freeze({width: ARENA_WIDTH, height: ARENA_HEIGHT}),
+		tickRate: TICKS_PER_SECOND,
+		maxTicks,
+	});
+
+	resetAllHooks();
+
+	const initialState = createInitialState(seed, spawnDistance);
+	const history: GameState[] = skipHistory ? [] : [initialState];
+	let currentTick = 0;
+	let wizards: InternalWizardState[] = [
+		{
+			id: 'wizard-1',
+			position: {x: ARENA_WIDTH / 2 - spawnDistance / 2, y: ARENA_HEIGHT / 2},
+			rotation: 0,
+			health: WIZARD_HEALTH,
+			maxHealth: WIZARD_HEALTH,
+			state: 'idle',
+			blinkCooldown: 0,
+			velocity: {x: 0, y: 0},
+			damageDealt: 0,
+			damageTaken: 0,
+			lastHitTick: 0,
+		},
+		{
+			id: 'wizard-2',
+			position: {x: ARENA_WIDTH / 2 + spawnDistance / 2, y: ARENA_HEIGHT / 2},
+			rotation: 180,
+			health: WIZARD_HEALTH,
+			maxHealth: WIZARD_HEALTH,
+			state: 'idle',
+			blinkCooldown: 0,
+			velocity: {x: 0, y: 0},
+			damageDealt: 0,
+			damageTaken: 0,
+			lastHitTick: 0,
+		},
+	];
+	let projectiles: ProjectileState[] = [];
+	const missileAIs = new Map<string, MissileAIFunction>();
+	const allErrors: BotError[] = [];
+
+	while (currentTick < maxTicks)
+	{
+		const result = tick(currentTick, wizard1AI, wizard2AI, config, wizards, projectiles, missileAIs, seed);
+		currentTick = result.nextTick;
+		wizards = result.wizards;
+		projectiles = result.projectiles;
+		if (result.errors.length > 0) allErrors.push(...result.errors);
+
+		if (!skipHistory)
+		{
+			// Deep-clone snapshot for history (needed for replay)
+			history.push(getPlayerState(0, wizards, projectiles, currentTick));
+		}
+
+		if (wizards[0]!.health <= 0 || wizards[1]!.health <= 0)
+		{
+			break;
+		}
+	}
+
+	let winner: MatchWinner = null;
+	if (wizards[0]!.health <= 0 && wizards[1]!.health <= 0)
+	{
+		winner = 'draw';
+	}
+	else if (wizards[1]!.health <= 0)
+	{
+		winner = 'wizard-1';
+	}
+	else if (wizards[0]!.health <= 0)
+	{
+		winner = 'wizard-2';
+	}
+
+	// Always create final state snapshot (needed for result)
+	const finalState = getPlayerState(0, wizards, projectiles, currentTick);
+
+	return {
+		winner,
+		ticks: currentTick,
+		finalState,
+		history: skipHistory ? [] : history,
+		errors: allErrors,
+	};
+}