@vibemancer/core 0.1.0 → 0.1.1

package/src/bots/melee/03_Voidblade.ts

@@ -1,582 +1,582 @@
-import {WizardFunction} from '../../types.js';
-import {distanceTo} from '../../utils/distance.js';
-import {angleTo} from '../../utils/angles.js';
-import {
-	ARENA_SIZE,
-	GCD_DURATION,
-	SHIELD_CAST_TIME,
-	BLINK_CAST_TIME,
-} from '../../rules.js';
-import {
-	getThreats,
-	getMostUrgentThreat,
-	getDodgeDirectionForMovement,
-	getBlinkToDecreaseDistance,
-	shouldForceShield,
-	fitMissileToBudget,
-	MIN_USEFUL_DAMAGE,
-	getEnemyVulnerabilityTicks,
-} from '../shared.js';
-import {getMissileCastTime} from '../../utils/combat.js';
-import {useParam} from '../../engine/params-runtime.js';
-
-const WALL_BUFFER = 50;
-const SHIELD_BUFFER = 3;
-
-/**
- * Aggressive movement: dodge missiles, close distance, light strafe.
- */
-function aggressiveMove(
-	position: {x: number; y: number},
-	enemy: {position: {x: number; y: number}},
-	currentDistance: number,
-	dodgeDirection: {x: number; y: number} | null,
-	tick: number,
-	strafeCyclePeriod: number,
-	strafeIntensity: number,
-	approachSpeed: number,
-): {x: number; y: number} 
-{
-	const deltaX = enemy.position.x - position.x;
-	const deltaY = enemy.position.y - position.y;
-	const normalizedDistance = currentDistance > 0 ? currentDistance : 1;
-
-	const strafeClockwise = {
-		x: -deltaY / normalizedDistance,
-		y: deltaX / normalizedDistance,
-	};
-	const strafeCounterClockwise = {
-		x: deltaY / normalizedDistance,
-		y: -deltaX / normalizedDistance,
-	};
-
-	let strafeDirection: {x: number; y: number};
-
-	if (dodgeDirection) 
-	{
-		strafeDirection = dodgeDirection;
-	}
-	else if (
-		position.x < WALL_BUFFER ||
-    position.x > ARENA_SIZE - WALL_BUFFER ||
-    position.y < WALL_BUFFER ||
-    position.y > ARENA_SIZE - WALL_BUFFER
-	) 
-	{
-		const futureClockwise = {
-			x: position.x + strafeClockwise.x * 100,
-			y: position.y + strafeClockwise.y * 100,
-		};
-		const futureCounterClockwise = {
-			x: position.x + strafeCounterClockwise.x * 100,
-			y: position.y + strafeCounterClockwise.y * 100,
-		};
-		const scoreClockwise = Math.min(
-			futureClockwise.x,
-			ARENA_SIZE - futureClockwise.x,
-			futureClockwise.y,
-			ARENA_SIZE - futureClockwise.y,
-		);
-		const scoreCounterClockwise = Math.min(
-			futureCounterClockwise.x,
-			ARENA_SIZE - futureCounterClockwise.x,
-			futureCounterClockwise.y,
-			ARENA_SIZE - futureCounterClockwise.y,
-		);
-		strafeDirection =
-			scoreClockwise > scoreCounterClockwise
-				? strafeClockwise
-				: strafeCounterClockwise;
-	}
-	else 
-	{
-		const cycle = Math.floor(tick / strafeCyclePeriod) % 2;
-		strafeDirection = cycle === 0 ? strafeClockwise : strafeCounterClockwise;
-	}
-
-	if (dodgeDirection) 
-	{
-		return {x: strafeDirection.x * 100, y: strafeDirection.y * 100};
-	}
-
-	let moveX = strafeDirection.x * strafeIntensity;
-	let moveY = strafeDirection.y * strafeIntensity;
-
-	moveX += (deltaX / normalizedDistance) * approachSpeed;
-	moveY += (deltaY / normalizedDistance) * approachSpeed;
-
-	const magnitude = Math.sqrt(moveX * moveX + moveY * moveY);
-	if (magnitude > 100) 
-	{
-		moveX = (moveX / magnitude) * 100;
-		moveY = (moveY / magnitude) * 100;
-	}
-
-	return {x: moveX, y: moveY};
-}
-
-/**
- * Bot: Voidblade
- *
- * BEHAVIOR: Reactive counter-puncher. Shields everything, then fires quick stabs
- * during enemy vulnerability windows (GCD/casting) when they can't shield back.
- * At melee range, the shield blocks ~90% of incoming damage while Voidblade's
- * counter-stabs land at full damage — winning through attrition.
- *
- * CORE LOOP (melee range):
- *   1. Enemy casts missile → Voidblade blink-dodges (100% avoid) or shields (90% block)
- *   2. Enemy enters GCD → Voidblade fires quick stab (lands unblocked)
- *   3. Voidblade enters GCD → enemy recovers → repeat
- *
- * KEY IMPROVEMENTS OVER NIGHTBLADE:
- * - Blink-dodge priority: avoids 100% of damage when blink available, shields as fallback
- * - Reads enemy vulnerability to time counter-stabs perfectly
- * - Cancel-into-defense: aborts own cast if enemy missile incoming
- * - Punish budget: sizes stabs to fit exactly in the vulnerability window
- *
- * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
- * TIER: 3 (elite Melee line)
- */
-export const Voidblade: WizardFunction = ({state}) => 
-{
-	const preemptiveShieldRange = useParam('preemptiveShieldRange', 348, {
-		range: 85,
-		min: 50,
-		steps: 7,
-	});
-	const shieldWindow = useParam('shieldWindow', 18, {
-		range: 10,
-		min: 5,
-		max: 30,
-		steps: 5,
-	});
-	const punishMinVulnerability = useParam('punishMinVulnerability', 10, {
-		range: 15,
-		min: 10,
-		steps: 5,
-	});
-	const preferBlinkDodge =
-		useParam('preferBlinkDodge', 0, {min: 0, max: 1, steps: 2}) >= 0.5;
-	const strafeCyclePeriod = useParam('strafeCyclePeriod', 231, {
-		range: 75,
-		min: 80,
-		max: 250,
-	});
-	const strafeIntensity = useParam('strafeIntensity', 45, {
-		range: 30,
-		min: 10,
-		max: 80,
-		steps: 7,
-	});
-	const approachSpeed = useParam('approachSpeed', 92, {
-		range: 20,
-		min: 50,
-		max: 100,
-		steps: 7,
-	});
-	const shieldCancelThreshold = useParam('shieldCancelThreshold', 150, {
-		range: 75,
-		min: 50,
-		max: 300,
-	});
-	const blinkWindowMax = useParam('blinkWindowMax', 40, {
-		range: 30,
-		min: 15,
-		max: 80,
-		steps: 7,
-	});
-	const blinkPastMargin = useParam('blinkPastMargin', 50, {
-		range: 30,
-		min: 20,
-		max: 100,
-		steps: 7,
-	});
-	const blinkPastDistance = useParam('blinkPastDistance', 200, {
-		range: 100,
-		min: 50,
-		max: 350,
-		steps: 7,
-	});
-	const engageBlinkRange = useParam('engageBlinkRange', 30, {
-		range: 75,
-		min: 30,
-		max: 200,
-		steps: 7,
-	});
-	const counterStabRange = useParam('counterStabRange', 27, {
-		range: 20,
-		min: 10,
-		max: 60,
-		steps: 7,
-	});
-	const flightTimeDivisor = useParam('flightTimeDivisor', 7.5, {
-		range: 4,
-		min: 3,
-		max: 12,
-		steps: 5,
-	});
-	const enemyFlightTimeDivisor = useParam('enemyFlightTimeDivisor', 10, {
-		range: 4,
-		min: 2,
-		max: 10,
-		steps: 5,
-	});
-	const idleProvokeBudget = useParam('idleProvokeBudget', 37, {
-		range: 40,
-		min: 20,
-		max: 120,
-		steps: 7,
-	});
-	const meleeAbortRange = useParam('meleeAbortRange', 50, {
-		range: 50,
-		min: 50,
-		max: 200,
-		steps: 7,
-	});
-	const enemyFiringSoonThreshold = useParam('enemyFiringSoonThreshold', 50, {
-		range: 30,
-		min: 10,
-		max: 100,
-		steps: 7,
-	});
-
-	const enemy = state.enemies[0];
-	if (!enemy) 
-	{
-		return {move: {x: 0, y: 0}};
-	}
-
-	const distance = distanceTo(state.position, enemy.position);
-	const threats = getThreats(state);
-	const urgentThreat = getMostUrgentThreat(threats);
-	const dodgeDirection = getDodgeDirectionForMovement(threats, state.position);
-	const vulnerabilityTicks = getEnemyVulnerabilityTicks(enemy);
-
-	const move = aggressiveMove(
-		state.position,
-		enemy,
-		distance,
-		dodgeDirection,
-		state.tick,
-		strafeCyclePeriod,
-		strafeIntensity,
-		approachSpeed,
-	);
-
-	// Precompute blink targets — used by blink-dodge and engage-blink.
-	// blinkCloseTarget: from getBlinkToDecreaseDistance (dodge + close gap). Null at melee range.
-	// blinkPastTarget: blink ~200u past enemy (dodge only, loses position). For in-flight missiles only.
-	let blinkCloseTarget: {x: number; y: number} | null = null;
-	let blinkPastTarget: {x: number; y: number} | null = null;
-	if (state.blinkCooldown === 0) 
-	{
-		blinkCloseTarget = getBlinkToDecreaseDistance(
-			state.position,
-			enemy.position,
-			state.projectiles,
-		);
-		if (!blinkCloseTarget) 
-		{
-			const dx = enemy.position.x - state.position.x;
-			const dy = enemy.position.y - state.position.y;
-			const norm = Math.sqrt(dx * dx + dy * dy) || 1;
-			blinkPastTarget = {
-				x: Math.max(
-					blinkPastMargin,
-					Math.min(
-						ARENA_SIZE - blinkPastMargin,
-						state.position.x + (dx / norm) * blinkPastDistance,
-					),
-				),
-				y: Math.max(
-					blinkPastMargin,
-					Math.min(
-						ARENA_SIZE - blinkPastMargin,
-						state.position.y + (dy / norm) * blinkPastDistance,
-					),
-				),
-			};
-		}
-	}
-
-	// === STEP 1: CHANNELING — hold shield until missile passes ===
-	if (state.state === 'channeling') 
-	{
-		// Hold shield while there's an active threat OR enemy is about to fire
-		const enemyFiringSoon =
-			distance < preemptiveShieldRange &&
-      enemy.state === 'casting' &&
-      enemy.castingSpell === 'missile' &&
-      (enemy.castDuration ?? 0) -
-        (enemy.castProgress ?? 0) +
-        distance / enemyFlightTimeDivisor <
-        enemyFiringSoonThreshold;
-
-		if (
-			(!urgentThreat && !enemyFiringSoon) ||
-      (urgentThreat && urgentThreat.ticksToImpact > shieldCancelThreshold)
-		) 
-		{
-			return {move, cancel: true};
-		}
-		return {move: {x: 0, y: 0}};
-	}
-
-	// === STEP 2: CAST-CANCEL INTO DEFENSE ===
-	// If we're casting a stab and a missile is incoming, cancel so we can
-	// blink-dodge (if available) or shield. Defense time depends on blink availability.
-	if (state.state === 'casting' && state.castingSpell === 'missile') 
-	{
-		// Cancel if target escaped melee range
-		if (distance > meleeAbortRange) 
-		{
-			return {move, cancel: true};
-		}
-
-		// Defense time: blink (10t) is faster than shield (20t + 3t buffer)
-		const defenseTime =
-			state.blinkCooldown === 0
-				? BLINK_CAST_TIME
-				: SHIELD_CAST_TIME + SHIELD_BUFFER;
-
-		// Cancel for any undodgeable incoming threat we can't finish casting before
-		if (urgentThreat && !urgentThreat.bestDodgeDirection) 
-		{
-			const remainingCast =
-				(state.castDuration ?? 0) - (state.castProgress ?? 0);
-			const willArriveInWindow =
-				urgentThreat.ticksToImpact <=
-        remainingCast + GCD_DURATION + defenseTime;
-			if (willArriveInWindow) 
-			{
-				return {move, cancel: true};
-			}
-		}
-
-		// Cancel when enemy starts casting a missile at close range —
-		// at melee range their missile will arrive too fast to react after our cast finishes
-		if (
-			distance < preemptiveShieldRange &&
-      enemy.state === 'casting' &&
-      enemy.castingSpell === 'missile'
-		) 
-		{
-			const remainingEnemyCast =
-				(enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
-			const remainingOurCast =
-				(state.castDuration ?? 0) - (state.castProgress ?? 0);
-			const estimatedFlightTicks = distance / enemyFlightTimeDivisor;
-			const ticksUntilEnemyHit = remainingEnemyCast + estimatedFlightTicks;
-			const ticksAfterOurCast = remainingOurCast + GCD_DURATION + defenseTime;
-
-			// If enemy missile will arrive before we can defend after our cast, cancel now
-			if (ticksUntilEnemyHit < ticksAfterOurCast) 
-			{
-				return {move, cancel: true};
-			}
-		}
-	}
-
-	// === STEP 3: BLINK-DODGE — 100% damage avoidance (preferred over shield) ===
-	if (state.state === 'idle' && state.blinkCooldown === 0) 
-	{
-		// Blink target for dodging: close-gap target if available, else blink-past for in-flight only
-		const dodgeBlinkTarget = blinkCloseTarget ?? blinkPastTarget;
-
-		// 3a: Blink-dodge an in-flight missile (missile already fired, can't be cancelled)
-		if (
-			preferBlinkDodge &&
-      dodgeBlinkTarget &&
-      urgentThreat &&
-      urgentThreat.ticksToImpact >= 10 &&
-      urgentThreat.ticksToImpact <= blinkWindowMax
-		) 
-		{
-			return {
-				move: {x: 0, y: 0},
-				startCast: {spell: 'blink', target: dodgeBlinkTarget},
-			};
-		}
-
-		// 3b: Preemptive blink-dodge — only when we have a close-gap target.
-		// At melee range, preemptive blink loses positioning (200u walk back) and
-		// the enemy can cancel their cast. Shield is better for preemptive defense.
-		if (
-			preferBlinkDodge &&
-      blinkCloseTarget &&
-      distance < preemptiveShieldRange &&
-      enemy.state === 'casting' &&
-      enemy.castingSpell === 'missile'
-		) 
-		{
-			const remainingCast =
-				(enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
-			const estimatedFlightTicks = distance / enemyFlightTimeDivisor;
-			const ticksUntilHit = remainingCast + estimatedFlightTicks;
-
-			if (
-				ticksUntilHit >= BLINK_CAST_TIME &&
-        ticksUntilHit < BLINK_CAST_TIME + shieldWindow
-			) 
-			{
-				return {
-					move: {x: 0, y: 0},
-					startCast: {spell: 'blink', target: blinkCloseTarget},
-				};
-			}
-		}
-
-		// 3c: Engage blink — close distance during enemy vulnerability (they can't react)
-		if (
-			blinkCloseTarget &&
-      distance > engageBlinkRange &&
-      vulnerabilityTicks >= punishMinVulnerability &&
-      (!urgentThreat || urgentThreat.bestDodgeDirection !== null)
-		) 
-		{
-			return {
-				move: {x: 0, y: 0},
-				startCast: {spell: 'blink', target: blinkCloseTarget},
-			};
-		}
-	}
-
-	// === STEP 4: SHIELD — fallback when blink can't help (90% block) ===
-
-	// 4a: Shield in-flight missiles
-	// Shield when: no blink target at all, or missile too close for blink (<10 ticks)
-	if (
-		state.state === 'idle' &&
-    urgentThreat &&
-    (!urgentThreat.bestDodgeDirection || shouldForceShield(urgentThreat)) &&
-    urgentThreat.canBlockInTime &&
-    ((!blinkCloseTarget && !blinkPastTarget) || urgentThreat.ticksToImpact < 10)
-	) 
-	{
-		return {
-			move: {x: 0, y: 0},
-			startCast: {spell: 'shield'},
-		};
-	}
-
-	// 4b: Preemptive shield — when blink can't close gap (melee range or cooldown)
-	if (
-		state.state === 'idle' &&
-    !blinkCloseTarget &&
-    distance < preemptiveShieldRange &&
-    enemy.state === 'casting' &&
-    enemy.castingSpell === 'missile'
-	) 
-	{
-		const remainingCast = (enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
-		const estimatedFlightTicks = distance / enemyFlightTimeDivisor;
-		const ticksUntilHit = remainingCast + estimatedFlightTicks;
-
-		if (
-			ticksUntilHit >= SHIELD_CAST_TIME &&
-      ticksUntilHit < SHIELD_CAST_TIME + shieldWindow
-		) 
-		{
-			return {
-				move: {x: 0, y: 0},
-				startCast: {spell: 'shield'},
-			};
-		}
-	}
-
-	// === STEP 5: COUNTER-STAB — fire during enemy vulnerability ===
-	// Only fire when enemy CAN'T shield (in GCD or mid-cast).
-	// Use small, fast stabs that fit within the vulnerability window.
-	if (state.state === 'idle' && distance < counterStabRange) 
-	{
-		const enemyHP = Math.ceil(enemy.health);
-		const flightTime = Math.ceil(distance / flightTimeDivisor) + 1;
-
-		if (vulnerabilityTicks >= punishMinVulnerability) 
-		{
-			// Budget: stab must land while enemy is still vulnerable
-			// castTime + flightTime < vulnerabilityTicks
-			const punishBudget = vulnerabilityTicks - flightTime;
-
-			// Also need time to shield if another missile is incoming
-			let nextThreatTime = urgentThreat?.ticksToImpact ?? Infinity;
-
-			// Account for enemy's active cast — their missile will arrive after cast completes + flight time
-			if (enemy.state === 'casting' && enemy.castingSpell === 'missile') 
-			{
-				const remainingEnemyCast =
-					(enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
-				const estimatedFlightTime = distance / enemyFlightTimeDivisor;
-				nextThreatTime = Math.min(
-					nextThreatTime,
-					remainingEnemyCast + estimatedFlightTime,
-				);
-			}
-
-			// Defense time: blink (10t) is faster than shield (20t + 3t buffer)
-			const defenseTime =
-				state.blinkCooldown === 0
-					? BLINK_CAST_TIME
-					: SHIELD_CAST_TIME + SHIELD_BUFFER;
-			const safeBudget = nextThreatTime - GCD_DURATION - defenseTime;
-			const effectiveBudget = Math.min(punishBudget, safeBudget);
-
-			if (effectiveBudget > 0) 
-			{
-				const config = fitMissileToBudget(effectiveBudget, distance, {
-					minTurnRate: 0,
-					maxDamage: enemyHP,
-					lastMissileConfig: state.lastMissileConfig,
-				});
-
-				if (config && config.damage >= MIN_USEFUL_DAMAGE) 
-				{
-					const castTime = getMissileCastTime(config, state.lastMissileConfig);
-					if (castTime + flightTime <= vulnerabilityTicks) 
-					{
-						return {
-							move,
-							startCast: {
-								spell: 'missile',
-								config,
-								missileAI: () => ({}),
-								direction: angleTo(state.position, enemy.position),
-							},
-						};
-					}
-				}
-			}
-		}
-
-		// Enemy is idle or channeling shield at close range — fire a quick stab to provoke.
-		// Idle: they must shield or eat damage.
-		// Channeling: shield blocks ~90% but 10% still lands. Stabs whittle HP so they
-		// can't just hold shield forever. Why: otherwise the bot waits for a
-		// vulnerability window that a channeling player never opens.
-		if ((enemy.state === 'idle' || enemy.state === 'channeling') && !urgentThreat)
-		{
-			// Use a small budget to keep stabs fast and stay reactive
-			const quickBudget = idleProvokeBudget;
-			const config = fitMissileToBudget(quickBudget, distance, {
-				minTurnRate: 0,
-				maxDamage: enemyHP,
-				lastMissileConfig: state.lastMissileConfig,
-			});
-
-			if (config) 
-			{
-				return {
-					move,
-					startCast: {
-						spell: 'missile',
-						config,
-						missileAI: () => ({}),
-						direction: angleTo(state.position, enemy.position),
-					},
-				};
-			}
-		}
-	}
-
-	return {move};
-};
+import {WizardFunction} from '../../types.js';
+import {distanceTo} from '../../utils/distance.js';
+import {angleTo} from '../../utils/angles.js';
+import {
+	ARENA_SIZE,
+	GCD_DURATION,
+	SHIELD_CAST_TIME,
+	BLINK_CAST_TIME,
+} from '../../rules.js';
+import {
+	getThreats,
+	getMostUrgentThreat,
+	getDodgeDirectionForMovement,
+	getBlinkToDecreaseDistance,
+	shouldForceShield,
+	fitMissileToBudget,
+	MIN_USEFUL_DAMAGE,
+	getEnemyVulnerabilityTicks,
+} from '../shared.js';
+import {getMissileCastTime} from '../../utils/combat.js';
+import {useParam} from '../../engine/params-runtime.js';
+
+const WALL_BUFFER = 50;
+const SHIELD_BUFFER = 3;
+
+/**
+ * Aggressive movement: dodge missiles, close distance, light strafe.
+ */
+function aggressiveMove(
+	position: {x: number; y: number},
+	enemy: {position: {x: number; y: number}},
+	currentDistance: number,
+	dodgeDirection: {x: number; y: number} | null,
+	tick: number,
+	strafeCyclePeriod: number,
+	strafeIntensity: number,
+	approachSpeed: number,
+): {x: number; y: number} 
+{
+	const deltaX = enemy.position.x - position.x;
+	const deltaY = enemy.position.y - position.y;
+	const normalizedDistance = currentDistance > 0 ? currentDistance : 1;
+
+	const strafeClockwise = {
+		x: -deltaY / normalizedDistance,
+		y: deltaX / normalizedDistance,
+	};
+	const strafeCounterClockwise = {
+		x: deltaY / normalizedDistance,
+		y: -deltaX / normalizedDistance,
+	};
+
+	let strafeDirection: {x: number; y: number};
+
+	if (dodgeDirection) 
+	{
+		strafeDirection = dodgeDirection;
+	}
+	else if (
+		position.x < WALL_BUFFER ||
+    position.x > ARENA_SIZE - WALL_BUFFER ||
+    position.y < WALL_BUFFER ||
+    position.y > ARENA_SIZE - WALL_BUFFER
+	) 
+	{
+		const futureClockwise = {
+			x: position.x + strafeClockwise.x * 100,
+			y: position.y + strafeClockwise.y * 100,
+		};
+		const futureCounterClockwise = {
+			x: position.x + strafeCounterClockwise.x * 100,
+			y: position.y + strafeCounterClockwise.y * 100,
+		};
+		const scoreClockwise = Math.min(
+			futureClockwise.x,
+			ARENA_SIZE - futureClockwise.x,
+			futureClockwise.y,
+			ARENA_SIZE - futureClockwise.y,
+		);
+		const scoreCounterClockwise = Math.min(
+			futureCounterClockwise.x,
+			ARENA_SIZE - futureCounterClockwise.x,
+			futureCounterClockwise.y,
+			ARENA_SIZE - futureCounterClockwise.y,
+		);
+		strafeDirection =
+			scoreClockwise > scoreCounterClockwise
+				? strafeClockwise
+				: strafeCounterClockwise;
+	}
+	else 
+	{
+		const cycle = Math.floor(tick / strafeCyclePeriod) % 2;
+		strafeDirection = cycle === 0 ? strafeClockwise : strafeCounterClockwise;
+	}
+
+	if (dodgeDirection) 
+	{
+		return {x: strafeDirection.x * 100, y: strafeDirection.y * 100};
+	}
+
+	let moveX = strafeDirection.x * strafeIntensity;
+	let moveY = strafeDirection.y * strafeIntensity;
+
+	moveX += (deltaX / normalizedDistance) * approachSpeed;
+	moveY += (deltaY / normalizedDistance) * approachSpeed;
+
+	const magnitude = Math.sqrt(moveX * moveX + moveY * moveY);
+	if (magnitude > 100) 
+	{
+		moveX = (moveX / magnitude) * 100;
+		moveY = (moveY / magnitude) * 100;
+	}
+
+	return {x: moveX, y: moveY};
+}
+
+/**
+ * Bot: Voidblade
+ *
+ * BEHAVIOR: Reactive counter-puncher. Shields everything, then fires quick stabs
+ * during enemy vulnerability windows (GCD/casting) when they can't shield back.
+ * At melee range, the shield blocks ~90% of incoming damage while Voidblade's
+ * counter-stabs land at full damage — winning through attrition.
+ *
+ * CORE LOOP (melee range):
+ *   1. Enemy casts missile → Voidblade blink-dodges (100% avoid) or shields (90% block)
+ *   2. Enemy enters GCD → Voidblade fires quick stab (lands unblocked)
+ *   3. Voidblade enters GCD → enemy recovers → repeat
+ *
+ * KEY IMPROVEMENTS OVER NIGHTBLADE:
+ * - Blink-dodge priority: avoids 100% of damage when blink available, shields as fallback
+ * - Reads enemy vulnerability to time counter-stabs perfectly
+ * - Cancel-into-defense: aborts own cast if enemy missile incoming
+ * - Punish budget: sizes stabs to fit exactly in the vulnerability window
+ *
+ * PROGRESSION LINE: Shadowblade → Nightblade → Voidblade
+ * TIER: 3 (elite Melee line)
+ */
+export const Voidblade: WizardFunction = ({state}) => 
+{
+	const preemptiveShieldRange = useParam('preemptiveShieldRange', 348, {
+		range: 85,
+		min: 50,
+		steps: 7,
+	});
+	const shieldWindow = useParam('shieldWindow', 18, {
+		range: 10,
+		min: 5,
+		max: 30,
+		steps: 5,
+	});
+	const punishMinVulnerability = useParam('punishMinVulnerability', 10, {
+		range: 15,
+		min: 10,
+		steps: 5,
+	});
+	const preferBlinkDodge =
+		useParam('preferBlinkDodge', 0, {min: 0, max: 1, steps: 2}) >= 0.5;
+	const strafeCyclePeriod = useParam('strafeCyclePeriod', 231, {
+		range: 75,
+		min: 80,
+		max: 250,
+	});
+	const strafeIntensity = useParam('strafeIntensity', 45, {
+		range: 30,
+		min: 10,
+		max: 80,
+		steps: 7,
+	});
+	const approachSpeed = useParam('approachSpeed', 92, {
+		range: 20,
+		min: 50,
+		max: 100,
+		steps: 7,
+	});
+	const shieldCancelThreshold = useParam('shieldCancelThreshold', 150, {
+		range: 75,
+		min: 50,
+		max: 300,
+	});
+	const blinkWindowMax = useParam('blinkWindowMax', 40, {
+		range: 30,
+		min: 15,
+		max: 80,
+		steps: 7,
+	});
+	const blinkPastMargin = useParam('blinkPastMargin', 50, {
+		range: 30,
+		min: 20,
+		max: 100,
+		steps: 7,
+	});
+	const blinkPastDistance = useParam('blinkPastDistance', 200, {
+		range: 100,
+		min: 50,
+		max: 350,
+		steps: 7,
+	});
+	const engageBlinkRange = useParam('engageBlinkRange', 30, {
+		range: 75,
+		min: 30,
+		max: 200,
+		steps: 7,
+	});
+	const counterStabRange = useParam('counterStabRange', 27, {
+		range: 20,
+		min: 10,
+		max: 60,
+		steps: 7,
+	});
+	const flightTimeDivisor = useParam('flightTimeDivisor', 7.5, {
+		range: 4,
+		min: 3,
+		max: 12,
+		steps: 5,
+	});
+	const enemyFlightTimeDivisor = useParam('enemyFlightTimeDivisor', 10, {
+		range: 4,
+		min: 2,
+		max: 10,
+		steps: 5,
+	});
+	const idleProvokeBudget = useParam('idleProvokeBudget', 37, {
+		range: 40,
+		min: 20,
+		max: 120,
+		steps: 7,
+	});
+	const meleeAbortRange = useParam('meleeAbortRange', 50, {
+		range: 50,
+		min: 50,
+		max: 200,
+		steps: 7,
+	});
+	const enemyFiringSoonThreshold = useParam('enemyFiringSoonThreshold', 50, {
+		range: 30,
+		min: 10,
+		max: 100,
+		steps: 7,
+	});
+
+	const enemy = state.enemies[0];
+	if (!enemy) 
+	{
+		return {move: {x: 0, y: 0}};
+	}
+
+	const distance = distanceTo(state.position, enemy.position);
+	const threats = getThreats(state);
+	const urgentThreat = getMostUrgentThreat(threats);
+	const dodgeDirection = getDodgeDirectionForMovement(threats, state.position);
+	const vulnerabilityTicks = getEnemyVulnerabilityTicks(enemy);
+
+	const move = aggressiveMove(
+		state.position,
+		enemy,
+		distance,
+		dodgeDirection,
+		state.tick,
+		strafeCyclePeriod,
+		strafeIntensity,
+		approachSpeed,
+	);
+
+	// Precompute blink targets — used by blink-dodge and engage-blink.
+	// blinkCloseTarget: from getBlinkToDecreaseDistance (dodge + close gap). Null at melee range.
+	// blinkPastTarget: blink ~200u past enemy (dodge only, loses position). For in-flight missiles only.
+	let blinkCloseTarget: {x: number; y: number} | null = null;
+	let blinkPastTarget: {x: number; y: number} | null = null;
+	if (state.blinkCooldown === 0) 
+	{
+		blinkCloseTarget = getBlinkToDecreaseDistance(
+			state.position,
+			enemy.position,
+			state.projectiles,
+		);
+		if (!blinkCloseTarget) 
+		{
+			const dx = enemy.position.x - state.position.x;
+			const dy = enemy.position.y - state.position.y;
+			const norm = Math.sqrt(dx * dx + dy * dy) || 1;
+			blinkPastTarget = {
+				x: Math.max(
+					blinkPastMargin,
+					Math.min(
+						ARENA_SIZE - blinkPastMargin,
+						state.position.x + (dx / norm) * blinkPastDistance,
+					),
+				),
+				y: Math.max(
+					blinkPastMargin,
+					Math.min(
+						ARENA_SIZE - blinkPastMargin,
+						state.position.y + (dy / norm) * blinkPastDistance,
+					),
+				),
+			};
+		}
+	}
+
+	// === STEP 1: CHANNELING — hold shield until missile passes ===
+	if (state.state === 'channeling') 
+	{
+		// Hold shield while there's an active threat OR enemy is about to fire
+		const enemyFiringSoon =
+			distance < preemptiveShieldRange &&
+      enemy.state === 'casting' &&
+      enemy.castingSpell === 'missile' &&
+      (enemy.castDuration ?? 0) -
+        (enemy.castProgress ?? 0) +
+        distance / enemyFlightTimeDivisor <
+        enemyFiringSoonThreshold;
+
+		if (
+			(!urgentThreat && !enemyFiringSoon) ||
+      (urgentThreat && urgentThreat.ticksToImpact > shieldCancelThreshold)
+		) 
+		{
+			return {move, cancel: true};
+		}
+		return {move: {x: 0, y: 0}};
+	}
+
+	// === STEP 2: CAST-CANCEL INTO DEFENSE ===
+	// If we're casting a stab and a missile is incoming, cancel so we can
+	// blink-dodge (if available) or shield. Defense time depends on blink availability.
+	if (state.state === 'casting' && state.castingSpell === 'missile') 
+	{
+		// Cancel if target escaped melee range
+		if (distance > meleeAbortRange) 
+		{
+			return {move, cancel: true};
+		}
+
+		// Defense time: blink (10t) is faster than shield (20t + 3t buffer)
+		const defenseTime =
+			state.blinkCooldown === 0
+				? BLINK_CAST_TIME
+				: SHIELD_CAST_TIME + SHIELD_BUFFER;
+
+		// Cancel for any undodgeable incoming threat we can't finish casting before
+		if (urgentThreat && !urgentThreat.bestDodgeDirection) 
+		{
+			const remainingCast =
+				(state.castDuration ?? 0) - (state.castProgress ?? 0);
+			const willArriveInWindow =
+				urgentThreat.ticksToImpact <=
+        remainingCast + GCD_DURATION + defenseTime;
+			if (willArriveInWindow) 
+			{
+				return {move, cancel: true};
+			}
+		}
+
+		// Cancel when enemy starts casting a missile at close range —
+		// at melee range their missile will arrive too fast to react after our cast finishes
+		if (
+			distance < preemptiveShieldRange &&
+      enemy.state === 'casting' &&
+      enemy.castingSpell === 'missile'
+		) 
+		{
+			const remainingEnemyCast =
+				(enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
+			const remainingOurCast =
+				(state.castDuration ?? 0) - (state.castProgress ?? 0);
+			const estimatedFlightTicks = distance / enemyFlightTimeDivisor;
+			const ticksUntilEnemyHit = remainingEnemyCast + estimatedFlightTicks;
+			const ticksAfterOurCast = remainingOurCast + GCD_DURATION + defenseTime;
+
+			// If enemy missile will arrive before we can defend after our cast, cancel now
+			if (ticksUntilEnemyHit < ticksAfterOurCast) 
+			{
+				return {move, cancel: true};
+			}
+		}
+	}
+
+	// === STEP 3: BLINK-DODGE — 100% damage avoidance (preferred over shield) ===
+	if (state.state === 'idle' && state.blinkCooldown === 0) 
+	{
+		// Blink target for dodging: close-gap target if available, else blink-past for in-flight only
+		const dodgeBlinkTarget = blinkCloseTarget ?? blinkPastTarget;
+
+		// 3a: Blink-dodge an in-flight missile (missile already fired, can't be cancelled)
+		if (
+			preferBlinkDodge &&
+      dodgeBlinkTarget &&
+      urgentThreat &&
+      urgentThreat.ticksToImpact >= 10 &&
+      urgentThreat.ticksToImpact <= blinkWindowMax
+		) 
+		{
+			return {
+				move: {x: 0, y: 0},
+				startCast: {spell: 'blink', target: dodgeBlinkTarget},
+			};
+		}
+
+		// 3b: Preemptive blink-dodge — only when we have a close-gap target.
+		// At melee range, preemptive blink loses positioning (200u walk back) and
+		// the enemy can cancel their cast. Shield is better for preemptive defense.
+		if (
+			preferBlinkDodge &&
+      blinkCloseTarget &&
+      distance < preemptiveShieldRange &&
+      enemy.state === 'casting' &&
+      enemy.castingSpell === 'missile'
+		) 
+		{
+			const remainingCast =
+				(enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
+			const estimatedFlightTicks = distance / enemyFlightTimeDivisor;
+			const ticksUntilHit = remainingCast + estimatedFlightTicks;
+
+			if (
+				ticksUntilHit >= BLINK_CAST_TIME &&
+        ticksUntilHit < BLINK_CAST_TIME + shieldWindow
+			) 
+			{
+				return {
+					move: {x: 0, y: 0},
+					startCast: {spell: 'blink', target: blinkCloseTarget},
+				};
+			}
+		}
+
+		// 3c: Engage blink — close distance during enemy vulnerability (they can't react)
+		if (
+			blinkCloseTarget &&
+      distance > engageBlinkRange &&
+      vulnerabilityTicks >= punishMinVulnerability &&
+      (!urgentThreat || urgentThreat.bestDodgeDirection !== null)
+		) 
+		{
+			return {
+				move: {x: 0, y: 0},
+				startCast: {spell: 'blink', target: blinkCloseTarget},
+			};
+		}
+	}
+
+	// === STEP 4: SHIELD — fallback when blink can't help (90% block) ===
+
+	// 4a: Shield in-flight missiles
+	// Shield when: no blink target at all, or missile too close for blink (<10 ticks)
+	if (
+		state.state === 'idle' &&
+    urgentThreat &&
+    (!urgentThreat.bestDodgeDirection || shouldForceShield(urgentThreat)) &&
+    urgentThreat.canBlockInTime &&
+    ((!blinkCloseTarget && !blinkPastTarget) || urgentThreat.ticksToImpact < 10)
+	) 
+	{
+		return {
+			move: {x: 0, y: 0},
+			startCast: {spell: 'shield'},
+		};
+	}
+
+	// 4b: Preemptive shield — when blink can't close gap (melee range or cooldown)
+	if (
+		state.state === 'idle' &&
+    !blinkCloseTarget &&
+    distance < preemptiveShieldRange &&
+    enemy.state === 'casting' &&
+    enemy.castingSpell === 'missile'
+	) 
+	{
+		const remainingCast = (enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
+		const estimatedFlightTicks = distance / enemyFlightTimeDivisor;
+		const ticksUntilHit = remainingCast + estimatedFlightTicks;
+
+		if (
+			ticksUntilHit >= SHIELD_CAST_TIME &&
+      ticksUntilHit < SHIELD_CAST_TIME + shieldWindow
+		) 
+		{
+			return {
+				move: {x: 0, y: 0},
+				startCast: {spell: 'shield'},
+			};
+		}
+	}
+
+	// === STEP 5: COUNTER-STAB — fire during enemy vulnerability ===
+	// Only fire when enemy CAN'T shield (in GCD or mid-cast).
+	// Use small, fast stabs that fit within the vulnerability window.
+	if (state.state === 'idle' && distance < counterStabRange) 
+	{
+		const enemyHP = Math.ceil(enemy.health);
+		const flightTime = Math.ceil(distance / flightTimeDivisor) + 1;
+
+		if (vulnerabilityTicks >= punishMinVulnerability) 
+		{
+			// Budget: stab must land while enemy is still vulnerable
+			// castTime + flightTime < vulnerabilityTicks
+			const punishBudget = vulnerabilityTicks - flightTime;
+
+			// Also need time to shield if another missile is incoming
+			let nextThreatTime = urgentThreat?.ticksToImpact ?? Infinity;
+
+			// Account for enemy's active cast — their missile will arrive after cast completes + flight time
+			if (enemy.state === 'casting' && enemy.castingSpell === 'missile') 
+			{
+				const remainingEnemyCast =
+					(enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
+				const estimatedFlightTime = distance / enemyFlightTimeDivisor;
+				nextThreatTime = Math.min(
+					nextThreatTime,
+					remainingEnemyCast + estimatedFlightTime,
+				);
+			}
+
+			// Defense time: blink (10t) is faster than shield (20t + 3t buffer)
+			const defenseTime =
+				state.blinkCooldown === 0
+					? BLINK_CAST_TIME
+					: SHIELD_CAST_TIME + SHIELD_BUFFER;
+			const safeBudget = nextThreatTime - GCD_DURATION - defenseTime;
+			const effectiveBudget = Math.min(punishBudget, safeBudget);
+
+			if (effectiveBudget > 0) 
+			{
+				const config = fitMissileToBudget(effectiveBudget, distance, {
+					minTurnRate: 0,
+					maxDamage: enemyHP,
+					lastMissileConfig: state.lastMissileConfig,
+				});
+
+				if (config && config.damage >= MIN_USEFUL_DAMAGE) 
+				{
+					const castTime = getMissileCastTime(config, state.lastMissileConfig);
+					if (castTime + flightTime <= vulnerabilityTicks) 
+					{
+						return {
+							move,
+							startCast: {
+								spell: 'missile',
+								config,
+								missileAI: () => ({}),
+								direction: angleTo(state.position, enemy.position),
+							},
+						};
+					}
+				}
+			}
+		}
+
+		// Enemy is idle or channeling shield at close range — fire a quick stab to provoke.
+		// Idle: they must shield or eat damage.
+		// Channeling: shield blocks ~90% but 10% still lands. Stabs whittle HP so they
+		// can't just hold shield forever. Why: otherwise the bot waits for a
+		// vulnerability window that a channeling player never opens.
+		if ((enemy.state === 'idle' || enemy.state === 'channeling') && !urgentThreat)
+		{
+			// Use a small budget to keep stabs fast and stay reactive
+			const quickBudget = idleProvokeBudget;
+			const config = fitMissileToBudget(quickBudget, distance, {
+				minTurnRate: 0,
+				maxDamage: enemyHP,
+				lastMissileConfig: state.lastMissileConfig,
+			});
+
+			if (config) 
+			{
+				return {
+					move,
+					startCast: {
+						spell: 'missile',
+						config,
+						missileAI: () => ({}),
+						direction: angleTo(state.position, enemy.position),
+					},
+				};
+			}
+		}
+	}
+
+	return {move};
+};