@vibemancer/core 0.1.0

package/src/bots/registry.ts

@@ -0,0 +1,207 @@
+/**
+ * VIBEMANCER - BOT REGISTRY
+ *
+ * Single source of truth for all bots, ordered from weakest to strongest.
+ * Run the tournament test to determine the correct ordering.
+ *
+ * To reorder: run `npx vitest run tests/bots/tournament.test.ts`
+ * and update the list below based on the results.
+ *
+ * BOT NAMING SCHEME (3-tier progression):
+ *
+ * | Group      | Tier 1 (base)  | Tier 2 (enhanced) | Tier 3 (elite)  |
+ * |------------|----------------|-------------------|-----------------|
+ * | Defensive  | Turtle         | Sentinel          | Golem           |
+ * | Duelist    | Battlemage     | Warmage           | Archmage        |
+ * | Homing     | Bonemancer     | Lich              | Archlich        |
+ * | Caster     | Flamecaller    | Pyromancer        | Infernalist     |
+ * | Melee      | Shadowblade    | Nightblade        | Voidblade       |
+ * | Sniper     | Spellshot      | Spelltracer       | Spellseeker     |
+ * | Berserker  | Stormchaser    | Stormcaller       | Stormforger     |
+ * | Kiter      | Spellspinner   | Spellweaver       | Spellbinder     |
+ *
+ * Standalone: TargetDummy, Critter, Hogger, Rookie, Doombringer
+ * Reserved: Spellslinger (future volume-of-fire archetype)
+ *
+ */
+
+import {WizardFunction} from '../types.js';
+import {TargetDummy} from './standalone/TargetDummy.js';
+import {Critter} from './standalone/Critter.js';
+import {Rookie} from './standalone/Rookie.js';
+import {Hogger} from './standalone/Hogger.js';
+import {Doombringer} from './standalone/Doombringer.js';
+import {Turtle} from './defensive/01_Turtle.js';
+import {Sentinel} from './defensive/02_Sentinel.js';
+import {Golem} from './defensive/03_Golem.js';
+import {Battlemage} from './duelist/01_Battlemage.js';
+import {Warmage} from './duelist/02_Warmage.js';
+import {Archmage} from './duelist/03_Archmage.js';
+import {Bonemancer} from './homing/01_Bonemancer.js';
+import {Lich} from './homing/02_Lich.js';
+import {Archlich} from './homing/03_Archlich.js';
+import {Flamecaller} from './caster/01_Flamecaller.js';
+import {Pyromancer} from './caster/02_Pyromancer.js';
+import {Infernalist} from './caster/03_Infernalist.js';
+import {Shadowblade} from './melee/01_Shadowblade.js';
+import {Nightblade} from './melee/02_Nightblade.js';
+import {Voidblade} from './melee/03_Voidblade.js';
+import {Spellshot} from './sniper/01_Spellshot.js';
+import {Spelltracer} from './sniper/02_Spelltracer.js';
+import {Spellseeker} from './sniper/03_Spellseeker.js';
+import {Stormchaser} from './berserker/01_Stormchaser.js';
+import {Stormcaller} from './berserker/02_Stormcaller.js';
+import {Stormforger} from './berserker/03_Stormforger.js';
+import {Spellspinner} from './kiter/01_Spellspinner.js';
+import {Spellweaver} from './kiter/02_Spellweaver.js';
+import {Spellbinder} from './kiter/03_Spellbinder.js';
+
+export interface BotEntry
+{
+	name: string;
+	ai: WizardFunction;
+	description: string;
+	tier?: number; // 1, 2, 3 for progression bots; undefined for standalone
+	group: string; // progression line name or 'Standalone'
+}
+
+export interface BotGroup
+{
+	label: string;
+	bots: BotEntry[];
+}
+
+/**
+ * All bots organized by progression line.
+ * Each group contains bots from the same archetype, ordered by tier.
+ */
+export const BOT_GROUPS: BotGroup[] = [
+	{
+		label: 'Standalone',
+		bots: [
+			{name: 'TargetDummy', ai: TargetDummy, description: 'Does nothing (for testing)', group: 'Standalone'},
+			{name: 'Critter', ai: Critter, description: 'Random actions (chaos test)', group: 'Standalone'},
+			{name: 'Rookie', ai: Rookie, description: 'Basic homing missiles', group: 'Standalone'},
+			{name: 'Hogger', ai: Hogger, description: 'Chaotic elite — random but dangerous', group: 'Standalone'},
+			{name: 'Doombringer', ai: Doombringer, description: 'Single max-damage shot benchmark', group: 'Standalone'},
+		],
+	},
+	{
+		label: 'Defensive',
+		bots: [
+			{name: 'Turtle', ai: Turtle, description: 'Stationary tank, last-moment shields', tier: 1, group: 'Defensive'},
+			{name: 'Sentinel', ai: Sentinel, description: 'Two-tier offense (big + fast missiles) + timed shields', tier: 2, group: 'Defensive'},
+			{name: 'Golem', ai: Golem, description: 'Stationary fortress, counterattack punish', tier: 3, group: 'Defensive'},
+		],
+	},
+	{
+		label: 'Melee',
+		bots: [
+			{name: 'Shadowblade', ai: Shadowblade, description: 'Blink-in melee assassin', tier: 1, group: 'Melee'},
+			{name: 'Nightblade', ai: Nightblade, description: '+ preemptive shields, smart stabs', tier: 2, group: 'Melee'},
+			{name: 'Voidblade', ai: Voidblade, description: '+ vulnerability engage, disengage mode', tier: 3, group: 'Melee'},
+		],
+	},
+	{
+		label: 'Homing',
+		bots: [
+			{name: 'Bonemancer', ai: Bonemancer, description: 'Slow homing missile spam', tier: 1, group: 'Homing'},
+			{name: 'Lich', ai: Lich, description: 'Slow missile swarm + defense', tier: 2, group: 'Homing'},
+			{name: 'Archlich', ai: Archlich, description: '+ vulnerability punish missiles during enemy GCD', tier: 3, group: 'Homing'},
+		],
+	},
+	{
+		label: 'Caster',
+		bots: [
+			{name: 'Flamecaller', ai: Flamecaller, description: 'Fixed homing missiles, long range', tier: 1, group: 'Caster'},
+			{name: 'Pyromancer', ai: Pyromancer, description: '+ adaptive fitting, cast canceling', tier: 2, group: 'Caster'},
+			{name: 'Infernalist', ai: Infernalist, description: '+ warmup exploitation, punish mode', tier: 3, group: 'Caster'},
+		],
+	},
+	{
+		label: 'Sniper',
+		bots: [
+			{name: 'Spellshot', ai: Spellshot, description: 'Intercept prediction shots', tier: 1, group: 'Sniper'},
+			{name: 'Spelltracer', ai: Spelltracer, description: '+ adaptive fitting, full defense', tier: 2, group: 'Sniper'},
+			{name: 'Spellseeker', ai: Spellseeker, description: '+ intercept-aimed punish, proactive kiting', tier: 3, group: 'Sniper'},
+		],
+	},
+	{
+		label: 'Duelist',
+		bots: [
+			{name: 'Battlemage', ai: Battlemage, description: 'Close-range fighter, cast interrupts', tier: 1, group: 'Duelist'},
+			{name: 'Warmage', ai: Warmage, description: '+ adaptive missile fitting', tier: 2, group: 'Duelist'},
+			{name: 'Archmage', ai: Archmage, description: '+ range-adaptive, HP-aware aggression', tier: 3, group: 'Duelist'},
+		],
+	},
+	{
+		label: 'Berserker',
+		bots: [
+			{name: 'Stormchaser', ai: Stormchaser, description: 'Aggressive trader, predictive homing', tier: 1, group: 'Berserker'},
+			{name: 'Stormcaller', ai: Stormcaller, description: '+ budget-fitted homing, smarter defense', tier: 2, group: 'Berserker'},
+			{name: 'Stormforger', ai: Stormforger, description: '+ vulnerability punish missiles during enemy GCD', tier: 3, group: 'Berserker'},
+		],
+	},
+	{
+		label: 'Kiter',
+		bots: [
+			{name: 'Spellspinner', ai: Spellspinner, description: 'Kiting with homing missiles', tier: 1, group: 'Kiter'},
+			{name: 'Spellweaver', ai: Spellweaver, description: '+ budget-fitted adaptive missiles', tier: 2, group: 'Kiter'},
+			{name: 'Spellbinder', ai: Spellbinder, description: '+ vulnerability punish missiles during enemy GCD', tier: 3, group: 'Kiter'},
+		],
+	},
+];
+
+// Flat map for lookup by name
+const BOT_MAP = new Map<string, BotEntry>();
+for (const group of BOT_GROUPS)
+{
+	for (const bot of group.bots)
+	{
+		BOT_MAP.set(bot.name, bot);
+	}
+}
+
+/**
+ * All bots ordered from weakest (#1) to strongest (#29).
+ * Based on round-robin tournament results.
+ * To update: run `npm run tournament`
+ */
+const ALL_BOTS_ORDER = [
+	'TargetDummy',   // #1  (1 pts,    0W)
+	'Critter',       // #2  (1 pts,    0W)
+	'Hogger',        // #3  (9 pts,   29W)
+	'Bonemancer',    // #4  (9 pts,   32W)
+	'Rookie',        // #5  (9 pts,   38W)
+	'Turtle',        // #6  (27 pts,  90W)
+	'Spellspinner',  // #7  (27 pts, 104W)
+	'Flamecaller',   // #8  (28 pts, 103W)
+	'Doombringer',   // #9  (30 pts, 108W)
+	'Golem',         // #10 (30 pts, 126W)
+	'Sentinel',      // #11 (30 pts,  98W)
+	'Shadowblade',   // #12 (33 pts, 120W)
+	'Stormchaser',   // #13 (36 pts, 116W)
+	'Warmage',       // #14 (39 pts, 144W)
+	'Battlemage',    // #15 (45 pts, 141W)
+	'Spellweaver',   // #16 (45 pts, 164W)
+	'Stormcaller',   // #17 (48 pts, 170W)
+	'Pyromancer',    // #18 (48 pts, 161W)
+	'Lich',          // #19 (51 pts, 165W)
+	'Archlich',      // #20 (58 pts, 184W)
+	'Infernalist',   // #21 (60 pts, 197W)
+	'Stormforger',   // #22 (60 pts, 211W)
+	'Spellshot',     // #23 (63 pts, 196W)
+	'Spelltracer',   // #24 (63 pts, 186W)
+	'Spellbinder',   // #25 (66 pts, 199W)
+	'Archmage',      // #26 (72 pts, 229W)
+	'Nightblade',    // #27 (72 pts, 230W)
+	'Spellseeker',   // #28 (76 pts, 243W)
+	'Voidblade',     // #29 (78 pts, 258W)
+];
+
+export const ALL_BOTS: BotEntry[] = ALL_BOTS_ORDER.map((name) =>
+{
+	const bot = BOT_MAP.get(name);
+	if (!bot) throw new Error(`Bot "${name}" not found in BOT_GROUPS`);
+	return bot;
+});

package/src/bots/shared.ts

@@ -0,0 +1,472 @@
+/**
+ * VIBEMANCER - SHARED BOT UTILITIES
+ *
+ * Common helpers used by multiple bots for threat analysis and defense.
+ */
+
+import {GameState, Position, ProjectileState} from '../types.js';
+import {analyzeThreats} from '../hooks/threat-analysis.js';
+import type {AnalyzedThreat} from '../hooks/types.js';
+import {distanceTo} from '../utils/distance.js';
+import {ARENA_SIZE, BLINK_RANGE, GCD_DURATION, SHIELD_CAST_TIME, WIZARD_RADIUS} from '../rules.js';
+
+// Re-export public utility so bots can import from shared
+export {fitMissileToBudget} from '../utils/combat.js';
+
+// T2 bots: max cast time when no threats are incoming (~2s)
+export const MAX_CAST_BUDGET = 200;
+
+// Minimum useful damage — d=1 to d=4 missiles waste cast time for negligible output.
+// When budget only allows this, fall back to firing a bigger missile and accept the hit.
+export const MIN_USEFUL_DAMAGE = 5;
+
+/**
+ * Compute how many ticks until the wizard can start a new action.
+ */
+export function computeTicksUntilReady(state: GameState): number
+{
+	switch (state.state)
+	{
+		case 'idle':
+			return 0;
+		case 'casting':
+			return (state.castDuration ?? 0) - (state.castProgress ?? 0);
+		case 'channeling':
+			return 0; // can cancel instantly
+		case 'gcd_locked':
+			return state.gcdRemaining ?? 0;
+		default:
+			return 0;
+	}
+}
+
+/**
+ * Get all threats from enemy projectiles using the simulation-based system.
+ */
+export function getThreats(state: GameState): AnalyzedThreat[]
+{
+	const ticksUntilReady = computeTicksUntilReady(state);
+	return analyzeThreats(state.position, state.projectiles, state.myProjectiles, ticksUntilReady);
+}
+
+/**
+ * Get the most urgent threat that will actually hit us.
+ * Returns null if no threats will hit.
+ */
+export function getMostUrgentThreat(threats: AnalyzedThreat[]): AnalyzedThreat | null
+{
+	// Threats are already sorted by ticksToImpact (soonest first)
+	return threats.find((t) => t.willHit) ?? null;
+}
+
+/**
+ * Determine if a threat should force a shield even when a dodge direction exists.
+ * High-damage homing missiles are too risky to dodge — the missile tracks the wizard
+ * and the dodge often fails. Shield instead to guarantee survival.
+ */
+export function shouldForceShield(threat: AnalyzedThreat): boolean
+{
+	return threat.projectile.damage >= 25 && threat.projectile.turnRate > 0;
+}
+
+/**
+ * Get a dodge direction for movement, even if no threat will directly hit.
+ * Homing missiles continuously adjust course, so even missiles the simulation
+ * says will "miss" should be dodged if they're close.
+ *
+ * Uses the missile's heading to determine which side it will pass the wizard,
+ * then dodges perpendicular to the heading, AWAY from the approach side.
+ * When the missile is heading dead-center at us (ambiguous), uses wall
+ * avoidance as a stable tiebreaker.
+ */
+export function getDodgeDirectionForMovement(
+	threats: AnalyzedThreat[],
+	myPos: Position,
+): Position | null
+{
+	// Only dodge missiles the simulation predicts will hit
+	const target = threats.find((t) => t.willHit) ?? null;
+
+	if (!target) return null;
+
+	// Missile heading direction (from its rotation)
+	const rad = target.projectile.rotation * (Math.PI / 180);
+	const missileDir = {x: Math.cos(rad), y: Math.sin(rad)};
+
+	// Vector from missile to wizard
+	const toWizard = {
+		x: myPos.x - target.projectile.position.x,
+		y: myPos.y - target.projectile.position.y,
+	};
+	const len = Math.sqrt(toWizard.x * toWizard.x + toWizard.y * toWizard.y);
+	if (len < 0.01) return null;
+
+	// Cross product: which side of the missile's path is the wizard on?
+	// cross > 0 → wizard is clockwise from heading → missile passes CCW → dodge CW (away)
+	// cross < 0 → wizard is counter-clockwise → missile passes CW → dodge CCW (away)
+	const cross = missileDir.x * toWizard.y - missileDir.y * toWizard.x;
+
+	// Perpendicular options to missile heading
+	const dodgeCW = {x: missileDir.y, y: -missileDir.x};
+	const dodgeCCW = {x: -missileDir.y, y: missileDir.x};
+
+	// Deadzone: missile heading nearly straight at us (~8° cone).
+	// Both sides are equally good, so use a stable tiebreaker.
+	const DEADZONE = 0.15 * len;
+
+	if (cross > DEADZONE)
+	{
+		return dodgeCCW;
+	}
+	if (cross < -DEADZONE)
+	{
+		return dodgeCW;
+	}
+
+	// Tiebreaker for dead-center missiles: pick the side further from walls
+	const futureA = {x: myPos.x + dodgeCCW.x * 100, y: myPos.y + dodgeCCW.y * 100};
+	const futureB = {x: myPos.x + dodgeCW.x * 100, y: myPos.y + dodgeCW.y * 100};
+	const scoreA = Math.min(futureA.x, ARENA_SIZE - futureA.x, futureA.y, ARENA_SIZE - futureA.y);
+	const scoreB = Math.min(futureB.x, ARENA_SIZE - futureB.x, futureB.y, ARENA_SIZE - futureB.y);
+
+	return scoreA >= scoreB ? dodgeCCW : dodgeCW;
+}
+
+/**
+ * Check if it's safe to start an attack (no imminent undodgeable threats).
+ *
+ * @param threats - Analyzed threats
+ * @param castTicks - How many ticks the attack cast will take
+ * @param gcdTicks - GCD ticks after cast (default 100)
+ * @param shieldCastTicks - Shield cast time (default 20)
+ */
+export function isSafeToAttack(
+	threats: AnalyzedThreat[],
+	castTicks: number,
+	gcdTicks: number = GCD_DURATION,
+	shieldCastTicks: number = SHIELD_CAST_TIME,
+): boolean
+{
+	// No threats = safe
+	const hittingThreats = threats.filter((t) => t.willHit);
+
+	for (const threat of hittingThreats)
+	{
+		if (threat.bestDodgeDirection !== null)
+		{
+			// Homing missiles track during GCD, but the wizard moves at full speed
+			// during GCD and can dodge normally. Only the cast (half speed) plus a
+			// transition buffer is truly dangerous for dodgeable homing missiles.
+			// Non-homing missiles only need dodging during the cast itself.
+			if (threat.projectile.turnRate > 0)
+			{
+				if (threat.ticksToImpact < castTicks + HOMING_DODGE_BUFFER)
+				{
+					return false;
+				}
+			}
+			else if (threat.ticksToImpact < castTicks)
+			{
+				return false;
+			}
+			continue;
+		}
+
+		// Undodgeable threat: we need time to finish cast + GCD + shield cast
+		const timeNeeded = castTicks + gcdTicks + shieldCastTicks + 1;
+		if (threat.ticksToImpact < timeNeeded)
+		{
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Calculate a blink target toward arena center (for emergency escapes).
+ */
+export function getBlinkToCenter(pos: Position): Position
+{
+	const centerX = ARENA_SIZE / 2;
+	const centerY = ARENA_SIZE / 2;
+	const dx = centerX - pos.x;
+	const dy = centerY - pos.y;
+	const dist = Math.sqrt(dx * dx + dy * dy);
+
+	if (dist === 0) return {x: centerX, y: centerY};
+
+	return {
+		x: pos.x + (dx / dist) * BLINK_RANGE,
+		y: pos.y + (dy / dist) * BLINK_RANGE,
+	};
+}
+
+// ============================================================================
+// BLINK DISTANCE FUNCTIONS
+// ============================================================================
+
+// Post-blink vulnerability: shield cast time before wizard can defend (blink has no GCD)
+const POST_BLINK_VULNERABILITY = SHIELD_CAST_TIME;
+
+// Approximate hit radius for missile safety (wizard radius + typical missile radius)
+const HIT_RADIUS = WIZARD_RADIUS + 3;
+
+// Homing missiles need extra buffer beyond cast time because they track during GCD
+const HOMING_DODGE_BUFFER = 20;
+
+// Minimum wall margin when evaluating blink targets (prevents blinking into walls)
+const BLINK_WALL_MARGIN = 20;
+
+// Minimum post-blink distance from enemy for escape blinks to be worthwhile
+export const MIN_BLINK_ESCAPE_DISTANCE = 250;
+
+// Scoring constants
+const ANGLE_CANDIDATES = 24; // every 15°
+const DISTANCE_FRACTIONS = [1.0, 0.7, 0.4];
+
+
+/**
+ * Find the best blink target to increase distance from an enemy.
+ * Avoids positions where missiles could arrive during the post-blink GCD window.
+ * Returns null if minResultDistance can't be achieved.
+ */
+export function getBlinkToIncreaseDistance(
+	myPos: Position,
+	enemyPos: Position,
+	projectiles: ProjectileState[],
+	minResultDistance?: number,
+): Position | null
+{
+	return findBestBlinkTarget(myPos, enemyPos, projectiles, 'increase', minResultDistance);
+}
+
+/**
+ * Find the best blink target to decrease distance to an enemy.
+ * Avoids positions where missiles could arrive during the post-blink GCD window.
+ */
+export function getBlinkToDecreaseDistance(
+	myPos: Position,
+	enemyPos: Position,
+	projectiles: ProjectileState[],
+): Position | null
+{
+	return findBestBlinkTarget(myPos, enemyPos, projectiles, 'decrease');
+}
+
+/**
+ * Core blink target finder. Evaluates candidates across multiple angles and distances,
+ * scoring by distance goal + wall safety + missile avoidance.
+ */
+function findBestBlinkTarget(
+	myPos: Position,
+	enemyPos: Position,
+	projectiles: ProjectileState[],
+	goal: 'increase' | 'decrease',
+	minResultDistance?: number,
+): Position | null
+{
+	const currentDist = distanceTo(myPos, enemyPos);
+
+	// Base direction: away from enemy (increase) or toward enemy (decrease)
+	let baseAngle: number;
+	if (currentDist < 0.01)
+	{
+		// Overlapping: fallback to toward center
+		baseAngle = Math.atan2(ARENA_SIZE / 2 - myPos.y, ARENA_SIZE / 2 - myPos.x);
+	}
+	else
+	{
+		const dx = goal === 'increase'
+			? myPos.x - enemyPos.x
+			: enemyPos.x - myPos.x;
+		const dy = goal === 'increase'
+			? myPos.y - enemyPos.y
+			: enemyPos.y - myPos.y;
+		baseAngle = Math.atan2(dy, dx);
+	}
+
+	// For decrease: don't overshoot past enemy
+	const maxBlinkDist = goal === 'decrease'
+		? Math.min(BLINK_RANGE, currentDist)
+		: BLINK_RANGE;
+
+	let bestTarget: Position | null = null;
+	let bestScore = -Infinity;
+
+	for (const fraction of DISTANCE_FRACTIONS)
+	{
+		const blinkDist = maxBlinkDist * fraction;
+		if (blinkDist < 10) continue;
+
+		for (let i = 0; i < ANGLE_CANDIDATES; i++)
+		{
+			const angle = baseAngle + (i * 2 * Math.PI) / ANGLE_CANDIDATES;
+
+			// Candidate position (clamped with wall buffer to prevent wall-hugging)
+			const cx = Math.max(BLINK_WALL_MARGIN, Math.min(ARENA_SIZE - BLINK_WALL_MARGIN, myPos.x + Math.cos(angle) * blinkDist));
+			const cy = Math.max(BLINK_WALL_MARGIN, Math.min(ARENA_SIZE - BLINK_WALL_MARGIN, myPos.y + Math.sin(angle) * blinkDist));
+
+			// Skip if clamping made this a non-blink
+			if (distanceTo(myPos, {x: cx, y: cy}) < 10) continue;
+
+			const candidate = {x: cx, y: cy};
+
+			// Score: distance from enemy (maximize for increase, minimize for decrease)
+			const enemyDist = distanceTo(candidate, enemyPos);
+			const distScore = goal === 'increase' ? enemyDist : -enemyDist;
+
+			// Penalize distance from arena center (prevents corner-trapping)
+			const center = ARENA_SIZE / 2;
+			const distFromCenter = distanceTo(candidate, {x: center, y: center});
+
+			// Missile danger penalty
+			const missilePenalty = getMissileDangerAtPosition(candidate, projectiles);
+
+			const score = distScore - distFromCenter * 0.5 - missilePenalty;
+
+			if (score > bestScore)
+			{
+				bestScore = score;
+				bestTarget = candidate;
+			}
+		}
+	}
+
+	// Check minResultDistance threshold
+	if (minResultDistance !== undefined && bestTarget !== null)
+	{
+		if (distanceTo(bestTarget, enemyPos) < minResultDistance)
+		{
+			return null;
+		}
+	}
+
+	return bestTarget;
+}
+
+/**
+ * Estimate missile danger at a position during the post-blink vulnerability window.
+ * Returns a penalty score (0 = safe, high = dangerous).
+ *
+ * Uses the missile's actual heading, speed, and turn rate to estimate arrival time.
+ * During GCD the wizard moves at full speed (1 u/tick), so missiles only threaten
+ * the blink destination if they arrive quickly enough that the wizard can't dodge.
+ */
+function getMissileDangerAtPosition(
+	pos: Position,
+	projectiles: ProjectileState[],
+): number
+{
+	let danger = 0;
+
+	for (const proj of projectiles)
+	{
+		const dx = pos.x - proj.position.x;
+		const dy = pos.y - proj.position.y;
+		const dist = Math.sqrt(dx * dx + dy * dy);
+
+		// Can the missile physically reach this position in time?
+		if (dist / proj.speed > POST_BLINK_VULNERABILITY) continue;
+
+		if (proj.turnRate > 0)
+		{
+			// Homing: estimate arrival using heading + turn rate + distance.
+			// The missile must turn toward the position AND travel to it.
+			// Minimum arrival ≈ max(turnTime, travelTime) since they overlap.
+			const angleToPos = Math.atan2(dy, dx) * (180 / Math.PI);
+			let angleDiff = angleToPos - proj.rotation;
+			while (angleDiff > 180) angleDiff -= 360;
+			while (angleDiff < -180) angleDiff += 360;
+
+			const turnTicks = Math.abs(angleDiff) / proj.turnRate;
+			const travelTicks = dist / proj.speed;
+			const estimatedArrival = Math.max(turnTicks, travelTicks);
+
+			// Only dangerous if it arrives before the wizard can move away.
+			// At full speed (1 u/tick), the wizard needs ~HIT_RADIUS ticks to
+			// sidestep out of the collision zone. Add a buffer for reaction.
+			if (estimatedArrival < HIT_RADIUS * 3)
+			{
+				danger += 1000;
+			}
+		}
+		else
+		{
+			// Non-homing: check if straight-line path passes near the position
+			const rad = proj.rotation * (Math.PI / 180);
+			const mx = Math.cos(rad);
+			const my = Math.sin(rad);
+
+			// Project position onto missile path (dot product)
+			const dot = dx * mx + dy * my;
+			if (dot < 0) continue; // missile heading away
+
+			// Closest point on missile path to candidate
+			const closestX = proj.position.x + mx * dot;
+			const closestY = proj.position.y + my * dot;
+			const closestDist = Math.sqrt(
+				(pos.x - closestX) ** 2 + (pos.y - closestY) ** 2,
+			);
+
+			// Check if path passes close enough to hit, within time window
+			if (closestDist < HIT_RADIUS * 3 && dot / proj.speed <= POST_BLINK_VULNERABILITY)
+			{
+				danger += 1000;
+			}
+		}
+	}
+
+	return danger;
+}
+
+
+// ============================================================================
+// T3 SHARED HELPERS
+// ============================================================================
+
+/**
+ * Compute how fast the enemy is closing distance (positive = approaching).
+ * Projects enemy velocity onto the vector from enemy to us.
+ */
+export function getClosingRate(
+	myPos: {x: number; y: number},
+	enemyPos: {x: number; y: number},
+	enemyVel: {x: number; y: number},
+): number
+{
+	const dx = myPos.x - enemyPos.x;
+	const dy = myPos.y - enemyPos.y;
+	const dist = Math.sqrt(dx * dx + dy * dy);
+	if (dist < 0.01) return 0;
+	return (enemyVel.x * dx + enemyVel.y * dy) / dist;
+}
+
+/**
+ * Compute how many ticks the enemy remains unable to shield.
+ * Casting missile → remaining cast + GCD. Casting blink/shield → remaining cast only.
+ * GCD-locked → remaining GCD. Idle/channeling → 0.
+ */
+export function getEnemyVulnerabilityTicks(enemy: {
+	state: string;
+	castingSpell?: string;
+	castProgress?: number;
+	castDuration?: number;
+	gcdRemaining?: number;
+}): number
+{
+	if (enemy.state === 'casting')
+	{
+		const remainingCast = (enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
+		if (enemy.castingSpell === 'missile')
+		{
+			return remainingCast + GCD_DURATION;
+		}
+		return remainingCast;
+	}
+	if (enemy.state === 'gcd_locked')
+	{
+		return enemy.gcdRemaining ?? 0;
+	}
+	return 0;
+}