@vibemancer/core 1.0.9 → 1.0.11

package/src/utils/combat.ts

@@ -1,371 +1,379 @@
-/**
- * VIBEMANCER - COMBAT UTILITIES
- *
- * Utilities for combat calculations.
- */
-
-import {Position, Velocity, MissileConfig} from '../types.js';
-import {
-	calculateMissileCastTime,
-	calculateWarmupMultiplier,
-	validateMissileConfig,
-	TICKS_PER_SECOND,
-	MOVEMENT_SPEED,
-	CASTING_MOVEMENT_MULT,
-	WIZARD_HEALTH,
-	MISSILE_BASE_CAST,
-	MISSILE_DAMAGE_SCALE,
-	MISSILE_DAMAGE_POWER,
-	MISSILE_HOMING_COEFF,
-	MISSILE_TURN_DURATION_COEFF,
-	MISSILE_SPEED_DURATION_COEFF,
-	MISSILE_SPEED_DURATION_BASELINE,
-	MISSILE_MIN_CAST_TIME,
-	MISSILE_MIN_DURATION,
-	MISSILE_MIN_DAMAGE,
-	WIZARD_RADIUS,
-	effectiveTurnRateCost,
-} from '../rules.js';
-
-/**
- * Get cast time in ticks for a missile configuration.
- * Applies the same clamps/validation as the engine before calculating,
- * so the result matches the actual cast time that will be used in-game.
- *
- * If lastMissileConfig is provided, includes warmup multiplier.
- * Pass undefined for first cast (full warmup) or null for base time only.
- */
-export function getMissileCastTime(config: MissileConfig, lastMissileConfig?: MissileConfig | null): number
-{
-	const validated = validateMissileConfig(config);
-	return Math.ceil(calculateMissileCastTime(validated, lastMissileConfig) * TICKS_PER_SECOND);
-}
-
-/**
- * Calculate the position to aim at to hit a moving target.
- * Returns the intercept point where a missile would hit the target.
- *
- * @param targetPos - Current target position
- * @param targetVel - Target velocity (units per tick)
- * @param missileSpeed - Missile speed (units per tick)
- * @param myPos - Shooter position
- * @returns The position to aim at
- */
-export function getLeadPosition(
-	targetPos: Position,
-	targetVel: Velocity,
-	missileSpeed: number,
-	myPos: Position,
-): Position
-{
-	// Vector from shooter to target
-	const dx = targetPos.x - myPos.x;
-	const dy = targetPos.y - myPos.y;
-
-	// Target velocity
-	const vx = targetVel.x;
-	const vy = targetVel.y;
-
-	// Quadratic coefficients for intercept time
-	// |target + velocity * t - shooter|^2 = (missileSpeed * t)^2
-	// Expands to: (vx^2 + vy^2 - speed^2) * t^2 + 2*(vx*dx + vy*dy) * t + (dx^2 + dy^2) = 0
-	const a = vx * vx + vy * vy - missileSpeed * missileSpeed;
-	const b = 2 * (vx * dx + vy * dy);
-	const c = dx * dx + dy * dy;
-
-	let t: number | null = null;
-
-	// Handle the linear case (|velocity| === missileSpeed)
-	if (Math.abs(a) < 1e-10)
-	{
-		if (Math.abs(b) > 1e-10)
-		{
-			const linearT = -c / b;
-			if (linearT > 0)
-			{
-				t = linearT;
-			}
-		}
-	}
-	else
-	{
-		// Quadratic case
-		const discriminant = b * b - 4 * a * c;
-
-		if (discriminant >= 0)
-		{
-			const sqrtD = Math.sqrt(discriminant);
-			const t1 = (-b + sqrtD) / (2 * a);
-			const t2 = (-b - sqrtD) / (2 * a);
-
-			if (t1 > 0 && t2 > 0)
-			{
-				t = Math.min(t1, t2);
-			}
-			else if (t1 > 0)
-			{
-				t = t1;
-			}
-			else if (t2 > 0)
-			{
-				t = t2;
-			}
-		}
-	}
-
-	// If no intercept solution, just aim at current position
-	if (t === null)
-	{
-		return {x: targetPos.x, y: targetPos.y};
-	}
-
-	// Calculate intercept position
-	return {
-		x: targetPos.x + vx * t,
-		y: targetPos.y + vy * t,
-	};
-}
-
-/**
- * Calculate optimal missile configuration based on target behavior.
- */
-export function getAdaptiveMissileConfig(
-	targetVelocity: Position,
-	distance: number,
-): {speed: number; turnRate: number; damage: number; duration: number}
-{
-	const targetSpeed = Math.sqrt(targetVelocity.x ** 2 + targetVelocity.y ** 2);
-
-	// Fast moving target = more homing
-	// Slow/stationary target = faster missile, light homing for correction
-	if (targetSpeed > 0.8)
-	{
-		// Moving target - use significant homing
-		const turnRate = Math.min(3, 1 + targetSpeed * 1.5);
-		return {
-			damage: 10,
-			speed: 5,
-			turnRate,
-			duration: Math.min(250, 100 + distance * 0.5),
-		};
-	}
-	else
-	{
-		// Stationary/slow target - faster missile with light homing for accuracy
-		return {
-			damage: 10,
-			speed: 6,
-			turnRate: 1, // Light homing to correct any aiming errors
-			duration: 180,
-		};
-	}
-}
-
-/**
- * Given a cast-time budget (in ticks) and a target distance, find the best
- * missile config that fits. Maximizes damage while ensuring the missile
- * can reach the target and finishes casting in time.
- *
- * Returns null if no useful missile fits in the budget.
- *
- * How it works: tries several speed/turnRate templates. For each, calculates
- * the minimum duration to reach `distance`, then solves the cast-time formula
- * for the maximum damage that fits within `budgetTicks`.
- *
- * If `lastMissileConfig` is provided, accounts for warmup bonus: similar
- * missiles cast faster, so more damage can fit in the same budget.
- */
-/**
- * Simulate a missile trajectory to find the minimum duration (ticks) needed
- * to reach a target at the given distance. Works for all turnRate values:
- * positive (homing) and zero (straight).
- *
- * The simulation starts the missile aimed directly at the target and steps
- * through the trajectory tick by tick. For homing, the missile tracks the
- * target each tick matching the engine's steering physics.
- */
-/**
- * Simulate a missile trajectory to find the minimum duration (ticks) needed
- * to reach a target at the given distance. Works for straight (turnRate=0)
- * and homing (turnRate>0) missiles.
- *
- * The missile starts aimed directly at the target at (dist, 0) and steps
- * through the trajectory tick by tick. For homing, the missile tracks the
- * target each tick matching the engine's steering physics.
- *
- * Returns 500 if the missile cannot reach the target within 500 ticks.
- */
-export function simulateMinDuration(speed: number, turnRateDeg: number, dist: number, collisionRadius?: number): number
-{
-	if (dist <= 0) return 1;
-	const hitR = collisionRadius ?? (WIZARD_RADIUS + 8);
-	if (turnRateDeg === 0)
-	{
-		return Math.max(1, Math.ceil((dist - hitR) / speed));
-	}
-	const maxTurn = Math.abs(turnRateDeg) * Math.PI / 180;
-	let angle = 0;
-	let x = 0;
-	let y = 0;
-	for (let t = 1; t <= 500; t++)
-	{
-		const targetAngle = Math.atan2(-y, dist - x);
-		let diff = targetAngle - angle;
-		while (diff > Math.PI) diff -= 2 * Math.PI;
-		while (diff < -Math.PI) diff += 2 * Math.PI;
-		const turn = Math.max(-maxTurn, Math.min(maxTurn, diff));
-		angle += turn;
-		x += Math.cos(angle) * speed;
-		y += Math.sin(angle) * speed;
-		const d = Math.sqrt((x - dist) * (x - dist) + y * y);
-		if (d <= hitR) return t;
-	}
-	return 500;
-}
-
-export function fitMissileToBudget(
-	budgetTicks: number,
-	distance: number,
-	options?: {minTurnRate?: number; maxDamage?: number; lastMissileConfig?: MissileConfig},
-): MissileConfig | null
-{
-
-	const budgetSec = budgetTicks / TICKS_PER_SECOND;
-	const minTurnRate = options?.minTurnRate ?? 0;
-	const maxDamage = options?.maxDamage ?? WIZARD_HEALTH;
-	// Warmup is active when caller explicitly passes lastMissileConfig in options.
-	// Value can be undefined (first cast = full warmup) or MissileConfig (similarity-based).
-	// When key is absent (old callers), no warmup is applied.
-	const warmupActive = options !== undefined && 'lastMissileConfig' in options;
-	const lastMissile = options?.lastMissileConfig;
-
-	// Minimum useful cast time is 10 ticks (0.1s)
-	if (budgetSec < MISSILE_MIN_CAST_TIME)
-	{
-		return null;
-	}
-
-	// Templates: [speed, turnRate] combos to try, ordered by preference.
-	// Lower turnRate = cheaper cast. Higher speed = shorter duration needed.
-	const templates: [number, number][] = [
-		[7, 0],   // Fast straight: cheapest cast, only hits stationary
-		[5, 0],   // Medium straight
-		[6, 0.5], // Fast with light tracking
-		[5, 1],   // Medium with tracking
-		[4, 1],   // Slow with tracking (long range)
-		[4, 1.5], // Slow with strong tracking
-		[3, 2],   // Very slow with heavy tracking (for aggressive homing)
-	];
-
-	let best: MissileConfig | null = null;
-	let bestDamage = 0;
-
-	for (const [speed, turnRate] of templates)
-	{
-		if (turnRate < minTurnRate) continue;
-		const minDurationTicks = Math.max(
-			MISSILE_MIN_DURATION,
-			simulateMinDuration(speed, turnRate, distance),
-		);
-		const durationSec = minDurationTicks / TICKS_PER_SECOND;
-
-		// Solve cast formula for damage:
-		// budgetSec = BASE + SCALE * d^POWER + delivery costs
-		// → d = ((budgetSec - fixedCost) / SCALE)^(1/POWER)
-		const turnCost = effectiveTurnRateCost(turnRate);
-		const fixedCost = MISSILE_BASE_CAST
-			+ MISSILE_HOMING_COEFF * turnCost
-			+ MISSILE_TURN_DURATION_COEFF * (turnCost * durationSec)
-			+ MISSILE_SPEED_DURATION_COEFF * (speed * durationSec - MISSILE_SPEED_DURATION_BASELINE);
-
-		// Estimate warmup multiplier for this template (depends on speed/turnRate/duration,
-		// not damage, so we can estimate before solving for damage)
-		let effectiveBudgetSec = budgetSec;
-		if (warmupActive && lastMissile)
-		{
-			const probe: MissileConfig = {damage: lastMissile.damage, speed, turnRate, duration: minDurationTicks};
-			const multiplier = calculateWarmupMultiplier(lastMissile, probe);
-			// multiplier < 1 = faster (more budget), > 1 = slower (less budget)
-			effectiveBudgetSec = budgetSec / multiplier;
-		}
-
-		const remaining = effectiveBudgetSec - fixedCost;
-		if (remaining <= 0)
-		{
-			continue;
-		}
-
-		const maxDamageFloat = Math.pow(remaining / MISSILE_DAMAGE_SCALE, 1 / MISSILE_DAMAGE_POWER);
-		const damage = Math.min(maxDamage, Math.floor(maxDamageFloat));
-
-		if (damage < MISSILE_MIN_DAMAGE)
-		{
-			continue;
-		}
-
-		// Verify actual cast time with real warmup (using final damage)
-		const candidate: MissileConfig = {damage, speed, turnRate, duration: minDurationTicks};
-		const actualCastSec = (warmupActive && lastMissile)
-			? calculateMissileCastTime(candidate, lastMissile)
-			: calculateMissileCastTime(candidate);
-		const actualCastTicks = Math.max(1, Math.ceil(actualCastSec * TICKS_PER_SECOND));
-
-		if (actualCastTicks > budgetTicks)
-		{
-			continue;
-		}
-
-		if (damage > bestDamage)
-		{
-			bestDamage = damage;
-			best = candidate;
-		}
-	}
-
-	return best;
-}
-
-/**
- * Fit a missile config that accounts for the enemy escaping during cast time.
- *
- * During casting, the caster moves at CASTING_MOVEMENT_MULT speed while
- * the enemy moves at full MOVEMENT_SPEED. This means the effective distance
- * at launch is larger than the current distance. This function iteratively
- * converges on a missile config whose range covers the escape distance.
- *
- * @param currentDistance - Current distance to enemy
- * @param budgetTicks - Maximum cast time budget in ticks
- * @param options - Same options as fitMissileToBudget, plus:
- *   - enemyApproaching: if true, enemy is moving toward caster (reduces escape)
- *   - distanceBuffer: flat units added to target distance for safety margin (default 20)
- *   - maxIterations: convergence iterations (default 5)
- */
-export function fitMissileForEscapingTarget(
-	currentDistance: number,
-	budgetTicks: number,
-	options?: {minTurnRate?: number; maxDamage?: number; lastMissileConfig?: MissileConfig; enemyApproaching?: boolean; distanceBuffer?: number; maxIterations?: number},
-): MissileConfig | null
-{
-	const maxIter = options?.maxIterations ?? 5;
-	const buffer = options?.distanceBuffer ?? 20;
-	const escapeRate = options?.enemyApproaching
-		? 0
-		: MOVEMENT_SPEED - MOVEMENT_SPEED * CASTING_MOVEMENT_MULT;
-
-	let targetDistance = currentDistance + buffer;
-	let lastCastTicks = 0;
-
-	for (let i = 0; i < maxIter; i++)
-	{
-		const config = fitMissileToBudget(budgetTicks, targetDistance, options);
-		if (!config) return null;
-
-		const castTicks = getMissileCastTime(config, options?.lastMissileConfig);
-		if (castTicks === lastCastTicks) return config;
-		lastCastTicks = castTicks;
-
-		targetDistance = currentDistance + castTicks * escapeRate + buffer;
-	}
-
-	return fitMissileToBudget(budgetTicks, targetDistance, options);
-}
+/**
+ * VIBEMANCER - COMBAT UTILITIES
+ *
+ * Utilities for combat calculations.
+ */
+
+import {Position, Velocity, MissileConfig} from '../types.js';
+import {
+	calculateMissileCastTime,
+	calculateWarmupMultiplier,
+	validateMissileConfig,
+	TICKS_PER_SECOND,
+	MOVEMENT_SPEED,
+	CASTING_MOVEMENT_MULT,
+	WIZARD_HEALTH,
+	MISSILE_BASE_CAST,
+	MISSILE_DAMAGE_SCALE,
+	MISSILE_DAMAGE_POWER,
+	MISSILE_HOMING_COEFF,
+	MISSILE_TURN_DURATION_COEFF,
+	MISSILE_SPEED_DURATION_COEFF,
+	MISSILE_SPEED_DURATION_BASELINE,
+	MISSILE_MIN_CAST_TIME,
+	MISSILE_MIN_DURATION,
+	MISSILE_MIN_DAMAGE,
+	WIZARD_RADIUS,
+	effectiveTurnRateCost,
+} from '../rules.js';
+
+/**
+ * Get cast time in ticks for a missile configuration.
+ * Applies the same clamps/validation as the engine before calculating,
+ * so the result matches the actual cast time that will be used in-game.
+ *
+ * If lastMissileConfig is provided, includes warmup multiplier.
+ * Pass undefined for first cast (full warmup) or null for base time only.
+ *
+ * @returns cast time in TICKS.
+ *
+ * Note the unit, because there are two of these: `calculateMissileCastTime` in rules.ts has
+ * the identical signature and returns SECONDS. vibemancer_api lists both as
+ * `(config, last?) => number`, and the whole guide speaks in ticks — so a player budgeting
+ * ticks from the seconds one reads 2.747 as "about three ticks" when it is 275.
+ * This one is the one a bot wants.
+ */
+export function getMissileCastTime(config: MissileConfig, lastMissileConfig?: MissileConfig | null): number
+{
+	const validated = validateMissileConfig(config);
+	return Math.ceil(calculateMissileCastTime(validated, lastMissileConfig) * TICKS_PER_SECOND);
+}
+
+/**
+ * Calculate the position to aim at to hit a moving target.
+ * Returns the intercept point where a missile would hit the target.
+ *
+ * @param targetPos - Current target position
+ * @param targetVel - Target velocity (units per tick)
+ * @param missileSpeed - Missile speed (units per tick)
+ * @param myPos - Shooter position
+ * @returns The position to aim at
+ */
+export function getLeadPosition(
+	targetPos: Position,
+	targetVel: Velocity,
+	missileSpeed: number,
+	myPos: Position,
+): Position
+{
+	// Vector from shooter to target
+	const dx = targetPos.x - myPos.x;
+	const dy = targetPos.y - myPos.y;
+
+	// Target velocity
+	const vx = targetVel.x;
+	const vy = targetVel.y;
+
+	// Quadratic coefficients for intercept time
+	// |target + velocity * t - shooter|^2 = (missileSpeed * t)^2
+	// Expands to: (vx^2 + vy^2 - speed^2) * t^2 + 2*(vx*dx + vy*dy) * t + (dx^2 + dy^2) = 0
+	const a = vx * vx + vy * vy - missileSpeed * missileSpeed;
+	const b = 2 * (vx * dx + vy * dy);
+	const c = dx * dx + dy * dy;
+
+	let t: number | null = null;
+
+	// Handle the linear case (|velocity| === missileSpeed)
+	if (Math.abs(a) < 1e-10)
+	{
+		if (Math.abs(b) > 1e-10)
+		{
+			const linearT = -c / b;
+			if (linearT > 0)
+			{
+				t = linearT;
+			}
+		}
+	}
+	else
+	{
+		// Quadratic case
+		const discriminant = b * b - 4 * a * c;
+
+		if (discriminant >= 0)
+		{
+			const sqrtD = Math.sqrt(discriminant);
+			const t1 = (-b + sqrtD) / (2 * a);
+			const t2 = (-b - sqrtD) / (2 * a);
+
+			if (t1 > 0 && t2 > 0)
+			{
+				t = Math.min(t1, t2);
+			}
+			else if (t1 > 0)
+			{
+				t = t1;
+			}
+			else if (t2 > 0)
+			{
+				t = t2;
+			}
+		}
+	}
+
+	// If no intercept solution, just aim at current position
+	if (t === null)
+	{
+		return {x: targetPos.x, y: targetPos.y};
+	}
+
+	// Calculate intercept position
+	return {
+		x: targetPos.x + vx * t,
+		y: targetPos.y + vy * t,
+	};
+}
+
+/**
+ * Calculate optimal missile configuration based on target behavior.
+ */
+export function getAdaptiveMissileConfig(
+	targetVelocity: Position,
+	distance: number,
+): {speed: number; turnRate: number; damage: number; duration: number}
+{
+	const targetSpeed = Math.sqrt(targetVelocity.x ** 2 + targetVelocity.y ** 2);
+
+	// Fast moving target = more homing
+	// Slow/stationary target = faster missile, light homing for correction
+	if (targetSpeed > 0.8)
+	{
+		// Moving target - use significant homing
+		const turnRate = Math.min(3, 1 + targetSpeed * 1.5);
+		return {
+			damage: 10,
+			speed: 5,
+			turnRate,
+			duration: Math.min(250, 100 + distance * 0.5),
+		};
+	}
+	else
+	{
+		// Stationary/slow target - faster missile with light homing for accuracy
+		return {
+			damage: 10,
+			speed: 6,
+			turnRate: 1, // Light homing to correct any aiming errors
+			duration: 180,
+		};
+	}
+}
+
+/**
+ * Given a cast-time budget (in ticks) and a target distance, find the best
+ * missile config that fits. Maximizes damage while ensuring the missile
+ * can reach the target and finishes casting in time.
+ *
+ * Returns null if no useful missile fits in the budget.
+ *
+ * How it works: tries several speed/turnRate templates. For each, calculates
+ * the minimum duration to reach `distance`, then solves the cast-time formula
+ * for the maximum damage that fits within `budgetTicks`.
+ *
+ * If `lastMissileConfig` is provided, accounts for warmup bonus: similar
+ * missiles cast faster, so more damage can fit in the same budget.
+ */
+/**
+ * Simulate a missile trajectory to find the minimum duration (ticks) needed
+ * to reach a target at the given distance. Works for all turnRate values:
+ * positive (homing) and zero (straight).
+ *
+ * The simulation starts the missile aimed directly at the target and steps
+ * through the trajectory tick by tick. For homing, the missile tracks the
+ * target each tick matching the engine's steering physics.
+ */
+/**
+ * Simulate a missile trajectory to find the minimum duration (ticks) needed
+ * to reach a target at the given distance. Works for straight (turnRate=0)
+ * and homing (turnRate>0) missiles.
+ *
+ * The missile starts aimed directly at the target at (dist, 0) and steps
+ * through the trajectory tick by tick. For homing, the missile tracks the
+ * target each tick matching the engine's steering physics.
+ *
+ * Returns 500 if the missile cannot reach the target within 500 ticks.
+ */
+export function simulateMinDuration(speed: number, turnRateDeg: number, dist: number, collisionRadius?: number): number
+{
+	if (dist <= 0) return 1;
+	const hitR = collisionRadius ?? (WIZARD_RADIUS + 8);
+	if (turnRateDeg === 0)
+	{
+		return Math.max(1, Math.ceil((dist - hitR) / speed));
+	}
+	const maxTurn = Math.abs(turnRateDeg) * Math.PI / 180;
+	let angle = 0;
+	let x = 0;
+	let y = 0;
+	for (let t = 1; t <= 500; t++)
+	{
+		const targetAngle = Math.atan2(-y, dist - x);
+		let diff = targetAngle - angle;
+		while (diff > Math.PI) diff -= 2 * Math.PI;
+		while (diff < -Math.PI) diff += 2 * Math.PI;
+		const turn = Math.max(-maxTurn, Math.min(maxTurn, diff));
+		angle += turn;
+		x += Math.cos(angle) * speed;
+		y += Math.sin(angle) * speed;
+		const d = Math.sqrt((x - dist) * (x - dist) + y * y);
+		if (d <= hitR) return t;
+	}
+	return 500;
+}
+
+export function fitMissileToBudget(
+	budgetTicks: number,
+	distance: number,
+	options?: {minTurnRate?: number; maxDamage?: number; lastMissileConfig?: MissileConfig},
+): MissileConfig | null
+{
+
+	const budgetSec = budgetTicks / TICKS_PER_SECOND;
+	const minTurnRate = options?.minTurnRate ?? 0;
+	const maxDamage = options?.maxDamage ?? WIZARD_HEALTH;
+	// Warmup is active when caller explicitly passes lastMissileConfig in options.
+	// Value can be undefined (first cast = full warmup) or MissileConfig (similarity-based).
+	// When key is absent (old callers), no warmup is applied.
+	const warmupActive = options !== undefined && 'lastMissileConfig' in options;
+	const lastMissile = options?.lastMissileConfig;
+
+	// Minimum useful cast time is 10 ticks (0.1s)
+	if (budgetSec < MISSILE_MIN_CAST_TIME)
+	{
+		return null;
+	}
+
+	// Templates: [speed, turnRate] combos to try, ordered by preference.
+	// Lower turnRate = cheaper cast. Higher speed = shorter duration needed.
+	const templates: [number, number][] = [
+		[7, 0],   // Fast straight: cheapest cast, only hits stationary
+		[5, 0],   // Medium straight
+		[6, 0.5], // Fast with light tracking
+		[5, 1],   // Medium with tracking
+		[4, 1],   // Slow with tracking (long range)
+		[4, 1.5], // Slow with strong tracking
+		[3, 2],   // Very slow with heavy tracking (for aggressive homing)
+	];
+
+	let best: MissileConfig | null = null;
+	let bestDamage = 0;
+
+	for (const [speed, turnRate] of templates)
+	{
+		if (turnRate < minTurnRate) continue;
+		const minDurationTicks = Math.max(
+			MISSILE_MIN_DURATION,
+			simulateMinDuration(speed, turnRate, distance),
+		);
+		const durationSec = minDurationTicks / TICKS_PER_SECOND;
+
+		// Solve cast formula for damage:
+		// budgetSec = BASE + SCALE * d^POWER + delivery costs
+		// → d = ((budgetSec - fixedCost) / SCALE)^(1/POWER)
+		const turnCost = effectiveTurnRateCost(turnRate);
+		const fixedCost = MISSILE_BASE_CAST
+			+ MISSILE_HOMING_COEFF * turnCost
+			+ MISSILE_TURN_DURATION_COEFF * (turnCost * durationSec)
+			+ MISSILE_SPEED_DURATION_COEFF * (speed * durationSec - MISSILE_SPEED_DURATION_BASELINE);
+
+		// Estimate warmup multiplier for this template (depends on speed/turnRate/duration,
+		// not damage, so we can estimate before solving for damage)
+		let effectiveBudgetSec = budgetSec;
+		if (warmupActive && lastMissile)
+		{
+			const probe: MissileConfig = {damage: lastMissile.damage, speed, turnRate, duration: minDurationTicks};
+			const multiplier = calculateWarmupMultiplier(lastMissile, probe);
+			// multiplier < 1 = faster (more budget), > 1 = slower (less budget)
+			effectiveBudgetSec = budgetSec / multiplier;
+		}
+
+		const remaining = effectiveBudgetSec - fixedCost;
+		if (remaining <= 0)
+		{
+			continue;
+		}
+
+		const maxDamageFloat = Math.pow(remaining / MISSILE_DAMAGE_SCALE, 1 / MISSILE_DAMAGE_POWER);
+		const damage = Math.min(maxDamage, Math.floor(maxDamageFloat));
+
+		if (damage < MISSILE_MIN_DAMAGE)
+		{
+			continue;
+		}
+
+		// Verify actual cast time with real warmup (using final damage)
+		const candidate: MissileConfig = {damage, speed, turnRate, duration: minDurationTicks};
+		const actualCastSec = (warmupActive && lastMissile)
+			? calculateMissileCastTime(candidate, lastMissile)
+			: calculateMissileCastTime(candidate);
+		const actualCastTicks = Math.max(1, Math.ceil(actualCastSec * TICKS_PER_SECOND));
+
+		if (actualCastTicks > budgetTicks)
+		{
+			continue;
+		}
+
+		if (damage > bestDamage)
+		{
+			bestDamage = damage;
+			best = candidate;
+		}
+	}
+
+	return best;
+}
+
+/**
+ * Fit a missile config that accounts for the enemy escaping during cast time.
+ *
+ * During casting, the caster moves at CASTING_MOVEMENT_MULT speed while
+ * the enemy moves at full MOVEMENT_SPEED. This means the effective distance
+ * at launch is larger than the current distance. This function iteratively
+ * converges on a missile config whose range covers the escape distance.
+ *
+ * @param currentDistance - Current distance to enemy
+ * @param budgetTicks - Maximum cast time budget in ticks
+ * @param options - Same options as fitMissileToBudget, plus:
+ *   - enemyApproaching: if true, enemy is moving toward caster (reduces escape)
+ *   - distanceBuffer: flat units added to target distance for safety margin (default 20)
+ *   - maxIterations: convergence iterations (default 5)
+ */
+export function fitMissileForEscapingTarget(
+	currentDistance: number,
+	budgetTicks: number,
+	options?: {minTurnRate?: number; maxDamage?: number; lastMissileConfig?: MissileConfig; enemyApproaching?: boolean; distanceBuffer?: number; maxIterations?: number},
+): MissileConfig | null
+{
+	const maxIter = options?.maxIterations ?? 5;
+	const buffer = options?.distanceBuffer ?? 20;
+	const escapeRate = options?.enemyApproaching
+		? 0
+		: MOVEMENT_SPEED - MOVEMENT_SPEED * CASTING_MOVEMENT_MULT;
+
+	let targetDistance = currentDistance + buffer;
+	let lastCastTicks = 0;
+
+	for (let i = 0; i < maxIter; i++)
+	{
+		const config = fitMissileToBudget(budgetTicks, targetDistance, options);
+		if (!config) return null;
+
+		const castTicks = getMissileCastTime(config, options?.lastMissileConfig);
+		if (castTicks === lastCastTicks) return config;
+		lastCastTicks = castTicks;
+
+		targetDistance = currentDistance + castTicks * escapeRate + buffer;
+	}
+
+	return fitMissileToBudget(budgetTicks, targetDistance, options);
+}