@vibemancer/core 0.1.3 → 0.1.5

package/src/engine/sandbox.ts

@@ -34,7 +34,7 @@ export interface SandboxOptions
 {
 	/** Memory limit in MB for the isolate (default: 512). */
 	memoryLimitMB?: number;
-	/** Timeout in ms for fight/simulate calls (default: 30000). */
+	/** Timeout in ms for fight/simulate calls (default: 60000). */
 	timeoutMs?: number;
 	/** Options passed to esbuild compilation (aliases, externals). */
 	compileOptions?: CompileOptions;
@@ -86,7 +86,7 @@ export class MatchSandbox
 	): Promise<MatchSandbox>
 	{
 		const memoryLimitMB = options?.memoryLimitMB ?? 512;
-		const timeoutMs = options?.timeoutMs ?? 30000;
+		const timeoutMs = options?.timeoutMs ?? 60000;
 
 		// 1. Compile the match bundle
 		const bundle = await compileMatchBundle(bot1, bot2, options?.compileOptions);
@@ -133,7 +133,7 @@ export class MatchSandbox
 	): Promise<MatchSandbox>
 	{
 		const memoryLimitMB = options?.memoryLimitMB ?? 512;
-		const timeoutMs = options?.timeoutMs ?? 30000;
+		const timeoutMs = options?.timeoutMs ?? 60000;
 
 		const isolate = new ivm.Isolate({memoryLimit: memoryLimitMB});
 

package/src/engine/simulation.ts

@@ -2,28 +2,30 @@ import {
 	GameState,
 	WizardState,
 	ProjectileState,
-	WizardFunction,
 	WizardActions,
-	MissileAIFunction,
 	MissileActions,
 	GameConfig,
 	MissileConfig,
 } from '../types.js';
+import type {SimEvent} from '../types.js';
+import type {WizardFunction, WizardContext, MissileContext, MissileFunction} from '../hooks/types.js';
+import {withWizardContext, withMissileContext} from './hooks-runtime.js';
+import {extractAction, extractMissileAction} from '../hooks/action-builders.js';
 import {
-	ARENA_WIDTH,
-	ARENA_HEIGHT,
+	RULES,
+	ARENA_SIZE,
+	ARENA_MIN,
+	ARENA_MAX,
 	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 {moveWizard, moveProjectile, sweptCircleCollision, clampToArena, resolveWizardCollision, isInLava} 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';
@@ -32,28 +34,36 @@ import {createRandom, createEntitySeed} from '../utils/random.js';
 export interface InternalWizardState extends WizardState
 {
 	missileConfig?: MissileConfig;
-	missileAI?: MissileAIFunction;
+	missileAI?: MissileFunction;
 	blinkTarget?: {x: number; y: number};
 	// Combat tracking
 	damageDealt: number;
 	damageTaken: number;
 	lastHitTick: number;
+	// Knockback velocity (decays over ticks)
+	knockbackVx?: number;
+	knockbackVy?: number;
+	// Delayed knockback (waits for explosion to expand)
+	knockbackDelay?: number;
+	knockbackPendingVx?: number;
+	knockbackPendingVy?: 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 center = {x: ARENA_SIZE / 2, y: ARENA_SIZE / 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,
+		health: RULES.WIZARD_HEALTH,
+		maxHealth: RULES.WIZARD_HEALTH,
 		state: 'idle',
 		blinkCooldown: 0,
 		velocity: {x: 0, y: 0},
@@ -63,8 +73,8 @@ export function createInitialState(_seed: number, spawnDist: number = SPAWN_DIST
 		id: 'wizard-2',
 		position: {x: center.x + offset, y: center.y},
 		rotation: 180,
-		health: WIZARD_HEALTH,
-		maxHealth: WIZARD_HEALTH,
+		health: RULES.WIZARD_HEALTH,
+		maxHealth: RULES.WIZARD_HEALTH,
 		state: 'idle',
 		blinkCooldown: 0,
 		velocity: {x: 0, y: 0},
@@ -85,6 +95,53 @@ export function createInitialState(_seed: number, spawnDist: number = SPAWN_DIST
 		damageDealt: 0,
 		damageTaken: 0,
 		lastHitTick: 0,
+		events: [],
+	};
+}
+
+/**
+ * Build a WizardContext from the simulation's GameState + GameConfig.
+ * This bridges the internal simulation state to the hooks API context.
+ */
+function buildWizardContext(state: GameState, config: GameConfig, random: () => number): WizardContext
+{
+	return {
+		entityId: 'unused', // overridden by runWithHooks
+		tick: state.tick,
+		random,
+		position: state.position,
+		velocity: state.velocity,
+		health: state.health,
+		maxHealth: state.maxHealth,
+		state: state.state,
+		castingSpell: state.castingSpell,
+		castProgress: state.castProgress,
+		castDuration: state.castDuration,
+		channelingSpell: state.channelingSpell,
+		channelDuration: state.channelDuration,
+		gcdRemaining: state.gcdRemaining,
+		blinkCooldown: state.blinkCooldown,
+		lastMissileConfig: state.lastMissileConfig,
+		enemies: state.enemies.map((e) => ({
+			id: e.id,
+			position: e.position,
+			velocity: e.velocity,
+			health: e.health,
+			state: e.state,
+			castingSpell: e.castingSpell,
+			castProgress: e.castProgress,
+			castDuration: e.castDuration,
+			gcdRemaining: e.gcdRemaining,
+			channelingSpell: e.channelingSpell,
+			channelDuration: e.channelDuration,
+		})),
+		projectiles: state.projectiles,
+		myProjectiles: state.myProjectiles,
+		arenaWidth: config.arenaSize.width,
+		arenaHeight: config.arenaSize.height,
+		damageDealt: state.damageDealt,
+		damageTaken: state.damageTaken,
+		lastHitTick: state.lastHitTick,
 	};
 }
 
@@ -98,17 +155,19 @@ export function tick(
 	config: GameConfig,
 	wizards: InternalWizardState[],
 	projectiles: ProjectileState[],
-	missileAIs: Map<string, MissileAIFunction>,
+	missileAIs: Map<string, MissileFunction>,
 	matchSeed: number,
 ): {
 	nextTick: number;
 	wizards: InternalWizardState[];
 	projectiles: ProjectileState[];
+	events: SimEvent[];
 	errors: BotError[];
 }
 {
 	const nextTick = currentTick + 1;
 	const errors: BotError[] = [];
+	const events: SimEvent[] = [];
 
 	// 1. Run wizard AIs with isolated random generators
 	// Each wizard gets a fresh random generator seeded by (matchSeed, wizardId, tick)
@@ -119,11 +178,9 @@ export function tick(
 	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}};
+		const stateView1 = getPlayerStateView(0, wizards, projectiles, nextTick);
+		const ctx1: WizardContext = buildWizardContext(stateView1, config, random1);
+		actions1 = runWithHooks(wizards[0]!.id, () => extractAction(withWizardContext(ctx1, wizard1AI))) ?? {move: {x: 0, y: 0}};
 	}
 	catch(e)
 	{
@@ -133,11 +190,9 @@ export function tick(
 	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}};
+		const stateView2 = getPlayerStateView(1, wizards, projectiles, nextTick);
+		const ctx2: WizardContext = buildWizardContext(stateView2, config, random2);
+		actions2 = runWithHooks(wizards[1]!.id, () => extractAction(withWizardContext(ctx2, wizard2AI))) ?? {move: {x: 0, y: 0}};
 	}
 	catch(e)
 	{
@@ -146,11 +201,39 @@ export function tick(
 
 	const actions = [actions1, actions2];
 
+	// 1b. Missile guide — freeze wizard, grant invulnerability, override missile steering
+	const guideOverrides = new Map<string, {x: number; y: number} | null>();
+	const guideInvincibleApplied: number[] = []; // wizard indices where we forced invincible
+	actions.forEach((action, i) =>
+	{
+		if (action.missileGuide)
+		{
+			const {missileId, direction} = action.missileGuide;
+			// Only apply if the missile actually exists and belongs to this wizard
+			const missile = projectiles.find((p) => p.id === missileId && p.ownerId === wizards[i]!.id);
+			if (missile)
+			{
+				// Freeze and protect the wizard (only set if not already invincible)
+				if (!wizards[i]!.invincible)
+				{
+					wizards[i]!.invincible = true;
+					guideInvincibleApplied.push(i);
+				}
+				action.move = {x: 0, y: 0};
+				// Store the direction override for the missile tick phase
+				guideOverrides.set(missileId, direction);
+			}
+		}
+	});
+
 	// 2. Update wizards
 	wizards.forEach((wizard, i) =>
 	{
 		const action = actions[i]!;
 
+		// Dead wizards do nothing during grace period
+		if (wizard.health <= 0) return;
+
 		// Handle cooldowns
 		if (wizard.blinkCooldown > 0)
 		{
@@ -203,6 +286,7 @@ export function tick(
 					};
 					projectiles.push(projectile);
 					missileAIs.set(id, wizard.missileAI);
+					events.push({type: 'missile-launch', position: {...wizard.position}, damage: validConfig.damage, speed: validConfig.speed, ownerId: wizard.id, rotation: wizard.rotation});
 					// Track last missile for warmup system
 					wizard.lastMissileConfig = {...validConfig};
 					delete wizard.missileConfig;
@@ -210,16 +294,16 @@ export function tick(
 				}
 				else if (spell === 'blink' && wizard.blinkTarget)
 				{
-					// Clamp blink target to BLINK_RANGE from current position
+					// Clamp blink target to RULES.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)
+					if (distance > RULES.BLINK_RANGE)
 					{
 						// Clamp to max range in the same direction
-						const scale = BLINK_RANGE / distance;
+						const scale = RULES.BLINK_RANGE / distance;
 						targetPos = {
 							x: wizard.position.x + dx * scale,
 							y: wizard.position.y + dy * scale,
@@ -227,16 +311,25 @@ export function tick(
 					}
 
 					// Clamp to arena bounds and calculate actual distance traveled
-					const oldPos = wizard.position;
+					const blinkFrom = {...wizard.position};
 					wizard.position = clampToArena(targetPos, WIZARD_RADIUS);
-					const actualDx = wizard.position.x - oldPos.x;
-					const actualDy = wizard.position.y - oldPos.y;
+					const actualDx = wizard.position.x - blinkFrom.x;
+					const actualDy = wizard.position.y - blinkFrom.y;
 					const actualDistance = Math.sqrt(actualDx * actualDx + actualDy * actualDy);
 					wizard.blinkCooldown = calculateBlinkCooldown(actualDistance);
 					delete wizard.blinkTarget;
+
+					events.push({type: 'blink', wizardId: wizard.id, from: blinkFrom, to: {...wizard.position}});
 				}
 
+				const completedSpell = spell;
 				completeCast(wizard);
+
+				// Emit shield-start when wizard transitions to channeling
+				if (completedSpell === 'shield')
+				{
+					events.push({type: 'shield-start', wizardId: wizard.id, position: {...wizard.position}});
+				}
 			}
 		}
 
@@ -244,6 +337,44 @@ export function tick(
 		const oldPos = wizard.position;
 		const move = action.move ?? {x: 0, y: 0};
 		wizard.position = moveWizard(wizard, move, 1);
+
+		// Process delayed knockback (apply impulse after delay expires)
+		if (wizard.knockbackDelay !== undefined && wizard.knockbackDelay > 0)
+		{
+			wizard.knockbackDelay--;
+			if (wizard.knockbackDelay <= 0)
+			{
+				wizard.knockbackVx = (wizard.knockbackVx ?? 0) + (wizard.knockbackPendingVx ?? 0);
+				wizard.knockbackVy = (wizard.knockbackVy ?? 0) + (wizard.knockbackPendingVy ?? 0);
+				wizard.knockbackDelay = undefined;
+				wizard.knockbackPendingVx = undefined;
+				wizard.knockbackPendingVy = undefined;
+			}
+		}
+
+		// Apply knockback velocity (decays each tick)
+		// Clamped to full arena (0-860), NOT playfield — can push into lava zones
+		if (wizard.knockbackVx || wizard.knockbackVy)
+		{
+			const kvx = wizard.knockbackVx ?? 0;
+			const kvy = wizard.knockbackVy ?? 0;
+			wizard.position = {
+				x: Math.max(0, Math.min(ARENA_SIZE, wizard.position.x + kvx)),
+				y: Math.max(0, Math.min(ARENA_SIZE, wizard.position.y + kvy)),
+			};
+			wizard.knockbackVx = kvx * RULES.KNOCKBACK_DECAY;
+			wizard.knockbackVy = kvy * RULES.KNOCKBACK_DECAY;
+			if (Math.abs(wizard.knockbackVx) < 0.1) wizard.knockbackVx = 0;
+			if (Math.abs(wizard.knockbackVy) < 0.1) wizard.knockbackVy = 0;
+		}
+
+		// Lava border: instant death if wizard is pushed or walks into lava
+		if (wizard.health > 0 && !wizard.invincible && isInLava(wizard.position, WIZARD_RADIUS))
+		{
+			wizard.health = 0;
+			events.push({type: 'wizard-lava-death', wizardId: wizard.id, position: {...wizard.position}});
+		}
+
 		wizard.velocity = {
 			x: wizard.position.x - oldPos.x,
 			y: wizard.position.y - oldPos.y,
@@ -255,6 +386,7 @@ export function tick(
 			updateShield(wizard, 1);
 			if (action.cancel)
 			{
+				events.push({type: 'cast-cancel', wizardId: wizard.id, position: {...wizard.position}, spell: 'shield'});
 				wizard.state = 'idle';
 				delete wizard.channelingSpell;
 				delete wizard.channelDuration;
@@ -270,8 +402,9 @@ export function tick(
 			}
 			else
 			{
-				startCast(wizard, action.startCast.spell, action.startCast.spell === 'missile' ? action.startCast.config : undefined);
-				if (action.startCast.spell === 'missile')
+				const castingSpell = action.startCast.spell;
+				startCast(wizard, castingSpell, castingSpell === 'missile' ? action.startCast.config : undefined);
+				if (castingSpell === 'missile')
 				{
 					wizard.missileConfig = action.startCast.config;
 					wizard.missileAI = action.startCast.missileAI;
@@ -280,16 +413,19 @@ export function tick(
 						wizard.rotation = action.startCast.direction;
 					}
 				}
-				else if (action.startCast.spell === 'blink')
+				else if (castingSpell === 'blink')
 				{
 					wizard.blinkTarget = action.startCast.target;
 				}
+
+				events.push({type: 'cast-start', wizardId: wizard.id, position: {...wizard.position}, spell: castingSpell});
 			}
 		}
 
 		// Handle cancel
 		if (wizard.state === 'casting' && action.cancel)
 		{
+			events.push({type: 'cast-cancel', wizardId: wizard.id, position: {...wizard.position}, spell: wizard.castingSpell ?? 'missile'});
 			wizard.state = 'idle';
 			delete wizard.castingSpell;
 			delete wizard.castProgress;
@@ -307,38 +443,70 @@ export function tick(
 	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));
+		// Check for missile guide override — skip normal AI and use player direction
+		const guideDir = guideOverrides.get(projectile.id);
+		const isGuided = guideOverrides.has(projectile.id);
+
+		let targetAngle: number | null = null;
 
-			// Wrap missile AI in try-catch - if it throws, missile continues straight (Lesson #21)
-			let missileActions: MissileActions = {};
-			try
+		if (isGuided)
+		{
+			// Guided missile: convert direction to target angle, or fly straight
+			if (guideDir && (guideDir.x !== 0 || guideDir.y !== 0))
 			{
-				missileActions = runWithHooks(projectile.id, () => ai({
-					missileState: projectileView(projectile),
-					worldState: getPlayerStateView(ownerIndex, wizards, projectiles, nextTick),
-					random: missileRandom,
-				})) ?? {};
+				targetAngle = (Math.atan2(guideDir.y, guideDir.x) * 180) / Math.PI;
 			}
-			catch(e)
+			// else: direction is null or zero → fly straight (targetAngle stays null)
+		}
+		else
+		{
+			const ai = missileAIs.get(projectile.id);
+			if (ai)
 			{
-				errors.push({tick: nextTick, entityId: projectile.id, message: e instanceof Error ? e.message : String(e)});
-			}
+				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));
+
+				// Build missile context for hooks-style missile AIs
+				const pView = projectileView(projectile);
+				const missileCtx: MissileContext = {
+					position: pView.position,
+					rotation: pView.rotation,
+					speed: pView.speed,
+					turnRate: pView.turnRate,
+					damage: pView.damage,
+					remainingTicks: pView.remainingTicks,
+					ownerId: pView.ownerId,
+					worldState: getPlayerStateView(ownerIndex, wizards, projectiles, nextTick),
+					random: missileRandom,
+				};
 
-			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);
+				// Wrap missile AI in try-catch - if it throws, missile continues straight (Lesson #21)
+				let missileActions: MissileActions = {};
+				try
+				{
+					missileActions = runWithHooks(projectile.id, () =>
+						extractMissileAction(withMissileContext(missileCtx, ai)),
+					) ?? {};
+				}
+				catch(e)
+				{
+					errors.push({tick: nextTick, entityId: projectile.id, message: e instanceof Error ? e.message : String(e)});
+				}
+
+				targetAngle = missileActions.turnToward
+					? angleTo(projectile.position, missileActions.turnToward)
+					: missileActions.turnToAngle !== undefined
+						? missileActions.turnToAngle
+						: null;
 			}
+		} // end else (not guided)
+
+		if (targetAngle !== null)
+		{
+			const diff = angleDiff(projectile.rotation, targetAngle);
+			const turn = Math.max(-projectile.turnRate, Math.min(projectile.turnRate, diff));
+			projectile.rotation = normalizeAngle(projectile.rotation + turn);
 		}
 
 		const oldPos = projectile.position;
@@ -350,7 +518,7 @@ export function tick(
 		const missileRadius = calculateMissileRadius(projectile.damage);
 		wizards.forEach((wizard) =>
 		{
-			if (wizard.id !== projectile.ownerId && !hit)
+			if (wizard.id !== projectile.ownerId && !hit && wizard.health > 0)
 			{
 				if (sweptCircleCollision(oldPos, projectile.position, missileRadius, wizard.position, WIZARD_RADIUS))
 				{
@@ -367,6 +535,35 @@ export function tick(
 					{
 						owner.damageDealt += actualDamage;
 					}
+
+					events.push({type: 'missile-hit', position: {...projectile.position}, damage: projectile.damage, actualDamage, speed: projectile.speed, ownerId: projectile.ownerId, targetId: wizard.id});
+
+					// Knockback: delayed impulse (waits for explosion to expand first)
+					const knockbackSpeed = Math.max(0, (projectile.damage - RULES.KNOCKBACK_DAMAGE_THRESHOLD) * RULES.KNOCKBACK_SPEED_PER_DAMAGE);
+					if (knockbackSpeed > 0)
+					{
+						const kdx = wizard.position.x - projectile.position.x;
+						const kdy = wizard.position.y - projectile.position.y;
+						const kdist = Math.sqrt(kdx * kdx + kdy * kdy);
+						if (kdist > 0)
+						{
+							wizard.knockbackDelay = RULES.KNOCKBACK_DELAY;
+							wizard.knockbackPendingVx = (kdx / kdist) * knockbackSpeed;
+							wizard.knockbackPendingVy = (kdy / kdist) * knockbackSpeed;
+						}
+					}
+
+					// Shield block event (actual damage < projectile damage means shield absorbed some)
+					if (actualDamage < projectile.damage && wizard.state === 'channeling')
+					{
+						events.push({type: 'shield-block', wizardId: wizard.id, position: {...wizard.position}, damageBlocked: projectile.damage - actualDamage, damageThrough: actualDamage});
+					}
+
+					// Emit wizard-death if health reached 0
+					if (wizard.health <= 0)
+					{
+						events.push({type: 'wizard-death', wizardId: wizard.id, position: {...wizard.position}});
+					}
 				}
 			}
 		});
@@ -374,9 +571,9 @@ export function tick(
 		// 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.x > ARENA_SIZE + ARENA_WATER_BUFFER ||
 			projectile.position.y < -ARENA_WATER_BUFFER ||
-			projectile.position.y > ARENA_HEIGHT + ARENA_WATER_BUFFER;
+			projectile.position.y > ARENA_SIZE + ARENA_WATER_BUFFER;
 
 		if (!hit && projectile.remainingTicks > 0 && !isOutOfBounds)
 		{
@@ -384,15 +581,25 @@ export function tick(
 		}
 		else
 		{
+			// Emit missile removal events (hit event already emitted above)
+			if (isOutOfBounds) events.push({type: 'missile-oob', position: {...projectile.position}});
+			else if (projectile.remainingTicks <= 0 && !hit) events.push({type: 'missile-expired', position: {...projectile.position}});
 			missileAIs.delete(projectile.id);
 			clearHooks(projectile.id);
 		}
 	});
 
+	// 4. Clear guide-applied invincibility so it doesn't persist beyond this tick
+	for (const idx of guideInvincibleApplied)
+	{
+		wizards[idx]!.invincible = false;
+	}
+
 	return {
 		nextTick,
 		wizards,
 		projectiles: remainingProjectiles,
+		events,
 		errors,
 	};
 }
@@ -443,7 +650,7 @@ function cloneProjectile(projectile: ProjectileState): ProjectileState
  * 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
+export function getPlayerState(playerIndex: number, wizards: InternalWizardState[], projectiles: ProjectileState[], tick: number, events: SimEvent[] = []): GameState
 {
 	const me = wizards[playerIndex]!;
 	const enemies = wizards.filter((_, i) => i !== playerIndex).map(cloneWizard);
@@ -473,6 +680,7 @@ export function getPlayerState(playerIndex: number, wizards: InternalWizardState
 		damageDealt: me.damageDealt,
 		damageTaken: me.damageTaken,
 		lastHitTick: me.lastHitTick,
+		events,
 	};
 }
 
@@ -561,6 +769,7 @@ function getPlayerStateView(playerIndex: number, wizards: InternalWizardState[],
 		damageDealt: me.damageDealt,
 		damageTaken: me.damageTaken,
 		lastHitTick: me.lastHitTick,
+		events: [], // AI views don't need events
 	};
 }
 
@@ -712,7 +921,6 @@ export function simulate(
 	} = {},
 ): SimulateResult
 {
-	// Validate AI functions (Lesson #1)
 	if (typeof wizard1AI !== 'function')
 	{
 		throw new Error('wizard1AI must be a function');
@@ -735,11 +943,11 @@ export function simulate(
 
 	// 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
+		? Math.min(rawSpawnDistance!, (ARENA_MAX - ARENA_MIN) - 100) // Leave room for wizards within playfield
 		: SPAWN_DISTANCE;
 
 	const config: GameConfig = Object.freeze({
-		arenaSize: Object.freeze({width: ARENA_WIDTH, height: ARENA_HEIGHT}),
+		arenaSize: Object.freeze({width: ARENA_SIZE, height: ARENA_SIZE}),
 		tickRate: TICKS_PER_SECOND,
 		maxTicks,
 	});
@@ -752,10 +960,10 @@ export function simulate(
 	let wizards: InternalWizardState[] = [
 		{
 			id: 'wizard-1',
-			position: {x: ARENA_WIDTH / 2 - spawnDistance / 2, y: ARENA_HEIGHT / 2},
+			position: {x: ARENA_SIZE / 2 - spawnDistance / 2, y: ARENA_SIZE / 2},
 			rotation: 0,
-			health: WIZARD_HEALTH,
-			maxHealth: WIZARD_HEALTH,
+			health: RULES.WIZARD_HEALTH,
+			maxHealth: RULES.WIZARD_HEALTH,
 			state: 'idle',
 			blinkCooldown: 0,
 			velocity: {x: 0, y: 0},
@@ -765,10 +973,10 @@ export function simulate(
 		},
 		{
 			id: 'wizard-2',
-			position: {x: ARENA_WIDTH / 2 + spawnDistance / 2, y: ARENA_HEIGHT / 2},
+			position: {x: ARENA_SIZE / 2 + spawnDistance / 2, y: ARENA_SIZE / 2},
 			rotation: 180,
-			health: WIZARD_HEALTH,
-			maxHealth: WIZARD_HEALTH,
+			health: RULES.WIZARD_HEALTH,
+			maxHealth: RULES.WIZARD_HEALTH,
 			state: 'idle',
 			blinkCooldown: 0,
 			velocity: {x: 0, y: 0},
@@ -778,9 +986,11 @@ export function simulate(
 		},
 	];
 	let projectiles: ProjectileState[] = [];
-	const missileAIs = new Map<string, MissileAIFunction>();
+	const missileAIs = new Map<string, MissileFunction>();
 	const allErrors: BotError[] = [];
 
+	let deathTick: number | null = null;
+
 	while (currentTick < maxTicks)
 	{
 		const result = tick(currentTick, wizard1AI, wizard2AI, config, wizards, projectiles, missileAIs, seed);
@@ -791,11 +1001,16 @@ export function simulate(
 
 		if (!skipHistory)
 		{
-			// Deep-clone snapshot for history (needed for replay)
-			history.push(getPlayerState(0, wizards, projectiles, currentTick));
+			// Deep-clone snapshot for history (needed for replay), including tick events
+			history.push(getPlayerState(0, wizards, projectiles, currentTick, result.events));
 		}
 
-		if (wizards[0]!.health <= 0 || wizards[1]!.health <= 0)
+		// Track death and add grace period (0.5s = 50 ticks at 100 tps)
+		if (!deathTick && (wizards[0]!.health <= 0 || wizards[1]!.health <= 0))
+		{
+			deathTick = currentTick;
+		}
+		if (deathTick && currentTick - deathTick >= 200)
 		{
 			break;
 		}