@vibemancer/core 0.1.4 → 0.1.5

package/src/bots/Hero.ts

@@ -0,0 +1,867 @@
+import type {FinalAction, MissileFunction} from '../hooks/index.js';
+import {usePosition, useEnemy, useStatus, useBlinkCooldown, useHealth, useTick, useThreats, useProjectiles, useMyProjectiles, useLastMissileConfig, useCastingSpell, useCastProgress, useRef, idle, move as moveAction, missile, shield, blink, cancel, getMissileContext, turnToward, flyStraight} from '../hooks/index.js';
+import {angleTo} from '../utils/angles.js';
+import {distanceTo} from '../utils/distance.js';
+import {RULES, ARENA_MIN, ARENA_MAX} from '../rules.js';
+import {getMissileCastTime, getLeadPosition} from '../utils/combat.js';
+import {
+	getMostUrgentThreat,
+	getDodgeDirectionForMovement,
+	fitMissileToBudget,
+	getBlinkToDecreaseDistance,
+	getBlinkToIncreaseDistance,
+	shouldForceShield,
+	MIN_BLINK_ESCAPE_DISTANCE,
+	MAX_CAST_BUDGET,
+	MIN_USEFUL_DAMAGE,
+	getEnemyVulnerabilityTicks,
+	isSafeToAttack,
+	keepOffWalls,
+	getPreCastReposition,
+} from './shared.js';
+import {useParam} from '../engine/params-runtime.js';
+import {Spellshot} from './sniper/01_Spellshot.js';
+
+const WALL_BUFFER = 60;
+const SHIELD_BUFFER = 3;
+// A single hit at/above this damage would (near-)one-shot Hero from full HP, so it is
+// never worth strafe-gambling — the dodge sim can misjudge a slow monster homer (e.g.
+// Doombringer's 60-dmg turn-0.5 missile) and one failed strafe = death. Treat such
+// lethal hits as undodgeable (cancel/blink/shield) like a hard-homer. No competitive
+// bot fires this big (all ≤30), so this only ever fires vs the max-damage benchmark.
+const LETHAL_HIT_DAMAGE = 50;
+// The sniper champion (Spellshot) uniquely fires spd-12 missiles (every other bot is
+// <= 11.3), so seeing one identifies it. Two exploits of its FIXED strategy, both gated on
+// this signature (zero competitive impact): (1) it force-shields incoming HOMING missiles
+// >= 25 dmg but eats smaller ones FULL, so cap our missiles at SNIPER_DAMAGE_CAP to slip
+// under the shield; (2) its snipes are dodgeable (turn-0.3) — we only eat them while
+// GCD-locked, so only cast in its post-fire GCD window, leaving us idle to dodge the rest.
+const SNIPER_MISSILE_SPEED = 11.5;
+const SNIPER_DAMAGE_CAP = 24;
+
+const HomingAI: MissileFunction = () =>
+{
+	const ctx = getMissileContext();
+	const enemy = ctx.worldState.enemies[0];
+	return enemy ? turnToward(enemy.position.x, enemy.position.y) : flyStraight();
+};
+
+const StraightAI: MissileFunction = () => flyStraight();
+
+function isNearWall(position: {x: number; y: number}): boolean
+{
+	return (
+		position.x < ARENA_MIN + WALL_BUFFER ||
+    position.x > ARENA_MAX - WALL_BUFFER ||
+    position.y < ARENA_MIN + WALL_BUFFER ||
+    position.y > ARENA_MAX - WALL_BUFFER
+	);
+}
+
+/**
+ * Smart combat movement with threat-aware dodging.
+ */
+function combatMove(
+	position: {x: number; y: number},
+	enemy: {position: {x: number; y: number}},
+	currentDistance: number,
+	targetDistance: number,
+	dodgeDirection: {x: number; y: number} | null,
+	tick: number,
+	strafeCyclePeriod: number,
+	strafeIntensity: number,
+	approachSpeed: number,
+	distanceDeadZone: number,
+	centerBias: 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;
+
+	// Approach the center-side of the enemy so knockback pushes toward center, not lava.
+	const center = (ARENA_MIN + ARENA_MAX) / 2;
+	const toCenterX = center - enemy.position.x;
+	const toCenterY = center - enemy.position.y;
+	const toCenterDist = Math.sqrt(toCenterX * toCenterX + toCenterY * toCenterY) || 1;
+	const approachDirX = deltaX / normalizedDistance + (toCenterX / toCenterDist) * centerBias;
+	const approachDirY = deltaY / normalizedDistance + (toCenterY / toCenterDist) * centerBias;
+	const approachMag = Math.sqrt(approachDirX * approachDirX + approachDirY * approachDirY) || 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 (isNearWall(position))
+	{
+		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_MIN,
+			ARENA_MAX - futureClockwise.x,
+			futureClockwise.y - ARENA_MIN,
+			ARENA_MAX - futureClockwise.y,
+		);
+		const scoreCounterClockwise = Math.min(
+			futureCounterClockwise.x - ARENA_MIN,
+			ARENA_MAX - futureCounterClockwise.x,
+			futureCounterClockwise.y - ARENA_MIN,
+			ARENA_MAX - 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, y: strafeDirection.y};
+	}
+
+	let moveX = strafeDirection.x * strafeIntensity;
+	let moveY = strafeDirection.y * strafeIntensity;
+
+	if (currentDistance > targetDistance + distanceDeadZone)
+	{
+		moveX += (approachDirX / approachMag) * approachSpeed;
+		moveY += (approachDirY / approachMag) * approachSpeed;
+	}
+	else if (currentDistance < targetDistance - distanceDeadZone)
+	{
+		let retreatX = -(deltaX / normalizedDistance) * approachSpeed;
+		let retreatY = -(deltaY / normalizedDistance) * approachSpeed;
+		if (position.x < ARENA_MIN + WALL_BUFFER && retreatX < 0) retreatX = 0;
+		if (position.x > ARENA_MAX - WALL_BUFFER && retreatX > 0) retreatX = 0;
+		if (position.y < ARENA_MIN + WALL_BUFFER && retreatY < 0) retreatY = 0;
+		if (position.y > ARENA_MAX - WALL_BUFFER && retreatY > 0) retreatY = 0;
+		moveX += retreatX;
+		moveY += retreatY;
+	}
+
+	const magnitude = Math.sqrt(moveX * moveX + moveY * moveY);
+	if (magnitude > 1)
+	{
+		moveX = moveX / magnitude;
+		moveY = moveY / magnitude;
+	}
+
+	return {x: moveX, y: moveY};
+}
+
+/**
+ * Bot: Hero
+ *
+ * BEHAVIOR: Adaptive duelist that classifies the opponent's range/missile style from
+ * live visible signals (how close they hold / whether they're closing, and their active
+ * missiles) and counters by adjusting engagement distance — KITE aggressors (close /
+ * closing / fast-straight stabbers) and CLOSE on kiters/casters (far / homing missiles).
+ * This opponent-classification layer sits on top of Archmage's HP-aware, range-adaptive
+ * engine: close range → straight missiles (no turn cost = more damage), mid/far → homing,
+ * aggressive dual-blink (gap-close during vulnerability, escape when a trade is bad), and
+ * HP-aware aggression (ahead → fight closer, behind → kite at range).
+ *
+ * KEY IMPROVEMENTS OVER ARCHMAGE:
+ * - Opponent classification: reads range/missile style and counters via distance offset
+ * - Counters aggressors by kiting, counters kiters/casters by closing in
+ *
+ * INHERITED FROM ARCHMAGE:
+ * - Range-adaptive missiles: straight close, homing far
+ * - Vulnerability-timed blinks: gap-close during enemy cast/GCD
+ * - HP-aware aggression: adjusts distance + risk tolerance based on HP differential
+ * - Progressive cast-cancel: graduated thresholds
+ */
+export function Hero(): FinalAction
+{
+	const position = usePosition();
+	const enemy = useEnemy();
+	const status = useStatus();
+	const blinkCooldown = useBlinkCooldown();
+	const health = useHealth();
+	const tick = useTick();
+	const threats = useThreats();
+	const projectiles = useProjectiles();
+	const myProjectiles = useMyProjectiles();
+	const lastMissileConfig = useLastMissileConfig();
+	const castingSpell = useCastingSpell();
+	const castProgressData = useCastProgress();
+
+
+	const targetDistance = useParam('targetDistance', 310, {
+		range: 150,
+		min: 0,
+	});
+	const minTurnRate = useParam('minTurnRate', 0.4, {range: 1.5, min: 0, steps: 5});
+	const blinkEscapeDistance = useParam('blinkEscapeDistance', 233, {
+		range: 190,
+		min: 0,
+		steps: 7,
+	});
+	const punishMinVulnerability = useParam('punishMinVulnerability', 35, {
+		range: 30,
+		min: 10,
+		steps: 5,
+	});
+	const aggressiveHPThreshold = useParam('aggressiveHPThreshold', 8, {
+		range: 20,
+		min: 0,
+		steps: 5,
+	});
+	const preferBlinkDodge =
+		useParam('preferBlinkDodge', 1, {min: 0, max: 1, steps: 2}) >= 0.5;
+	const strafeCyclePeriod = useParam('strafeCyclePeriod', 249, {
+		range: 75,
+		min: 80,
+		max: 250,
+	});
+	const strafeIntensity = useParam('strafeIntensity', 0.97, {
+		range: 0.4,
+		min: 0.2,
+		max: 1,
+		steps: 7,
+	});
+	const approachSpeed = useParam('approachSpeed', 0.7, {
+		range: 0.3,
+		min: 0.1,
+		max: 0.8,
+		steps: 7,
+	});
+	const distanceDeadZone = useParam('distanceDeadZone', 30, {
+		range: 30,
+		min: 10,
+		max: 80,
+		steps: 7,
+	});
+	const aggressiveDistanceOffset = useParam('aggressiveDistanceOffset', 11, {
+		range: 50,
+		min: 0,
+		max: 100,
+		steps: 7,
+	});
+	const cautiousDistanceOffset = useParam('cautiousDistanceOffset', 31, {
+		range: 50,
+		min: 0,
+		max: 120,
+		steps: 7,
+	});
+	const cancelHeavyDmg = useParam('cancelHeavyDmg', 30, {
+		range: 15,
+		min: 5,
+		max: 40,
+		steps: 5,
+	});
+	const cancelMediumDmg = useParam('cancelMediumDmg', 21, {
+		range: 10,
+		min: 3,
+		max: 25,
+		steps: 5,
+	});
+	const cancelCastRatio = useParam('cancelCastRatio', 0.6, {
+		range: 0.4,
+		min: 0.3,
+		max: 1.0,
+		steps: 5,
+	});
+	const shieldCancelThreshold = useParam('shieldCancelThreshold', 100, {
+		range: 75,
+		min: 50,
+		max: 300,
+	});
+	const blinkWindowMax = useParam('blinkWindowMax', 69, {
+		range: 40,
+		min: 20,
+		max: 120,
+		steps: 7,
+	});
+	const blinkGapThreshold = useParam('blinkGapThreshold', 111, {
+		range: 75,
+		min: 20,
+		max: 200,
+		steps: 7,
+	});
+	const flightTimeDivisor = useParam('flightTimeDivisor', 8.9, {
+		range: 4,
+		min: 2,
+		max: 12,
+		steps: 5,
+	});
+	const closeRangeStraightThreshold = useParam(
+		'closeRangeStraightThreshold',
+		50,
+		{range: 100, min: 50, max: 300, steps: 7},
+	);
+	const centerBias = useParam('centerBias', 0.48, {
+		range: 0.4,
+		min: 0,
+		max: 0.8,
+		steps: 5,
+	});
+	const maxBlinkDistance = useParam('maxBlinkDistance', 200, {
+		range: 100,
+		min: 50,
+		max: 300,
+		steps: 7,
+	});
+	// A missile whose turn rate is at/above this re-tracks faster than Hero can
+	// strafe clear, so the dodge sim wrongly reports it dodgeable. Treat such
+	// hard-homing missiles as undodgeable and defend (blink/shield) instead of
+	// strafing — cheap homing spam (e.g. dmg-12 turn-1) is the main attrition leak.
+	const hardHomingTurn = useParam('hardHomingTurn', 0.8, {
+		range: 0.7,
+		min: 0.3,
+		max: 2,
+		steps: 7,
+	});
+	// DEFENSIVE blinks (escaping a melee closer / breaking a hard-homing lock) get a
+	// larger reach than offensive gap-close blinks: blinking further clears fast
+	// point-blank stabbers and breaks homing locks, while offensive blinks stay short
+	// so they don't overshoot the enemy. (Blinking everyone further trades — it disrupts
+	// caster matchups like Pyromancer — so only the get-away blinks reach further.)
+	const escapeBlinkCap = useParam('escapeBlinkCap', 280, {
+		range: 100,
+		min: 150,
+		max: 320,
+		steps: 7,
+	});
+	// Enemy HP at/below which Hero goes for the KILL even into incoming fire — the
+	// match ends before their damage matters. Only fires when Hero will survive the
+	// in-flight hits, so it grabs close races (enemy left at 1 HP) without trading.
+	const finisherEnemyHP = useParam('finisherEnemyHP', 8, {
+		range: 8,
+		min: 1,
+		max: 20,
+		steps: 7,
+	});
+	// Sticky opponent model (persists per match, resets between). Once Hero has seen a
+	// lethal (≥LETHAL_HIT_DAMAGE) missile, it knows it faces the max-damage benchmark and
+	// holds arena-center for the rest of the match: at center every wall is ~400u away, so
+	// the ~330u knockback from that monster missile (shields don't block knockback) can
+	// never reach lava. Added at the END of the hook block to keep useParam indices stable.
+	const oppModel = useRef<{sawLethal: boolean; sawSniper: boolean; losingLatched: boolean; sawMidHomer: boolean; mirrorMatchTicks: number}>({sawLethal: false, sawSniper: false, losingLatched: false, sawMidHomer: false, mirrorMatchTicks: 0});
+
+	function capBlinkDistance(target: {x: number; y: number}, cap: number = maxBlinkDistance): {x: number; y: number}
+	{
+		const dx = target.x - position.x;
+		const dy = target.y - position.y;
+		const dist = Math.sqrt(dx * dx + dy * dy);
+		if (dist <= cap) return target;
+		const scale = cap / dist;
+		return {x: position.x + dx * scale, y: position.y + dy * scale};
+	}
+
+	// Blink perpendicular to an incoming missile's heading. Moving sideways to the
+	// missile's velocity breaks a homing lock harder than blinking toward/away from
+	// the enemy (which a tracker re-acquires), and lands 0 damage vs a shield's leak.
+	// Picks whichever of the two perpendicular sides stays further off walls/lava.
+	function blinkPerpendicularTo(proj: {position: {x: number; y: number}; rotation: number}): {x: number; y: number}
+	{
+		const rad = proj.rotation * (Math.PI / 180);
+		const hx = Math.cos(rad);
+		const hy = Math.sin(rad);
+		const wallScore = (t: {x: number; y: number}): number =>
+			Math.min(t.x - ARENA_MIN, ARENA_MAX - t.x, t.y - ARENA_MIN, ARENA_MAX - t.y);
+		const sideA = capBlinkDistance({x: position.x - hy * MIN_BLINK_ESCAPE_DISTANCE, y: position.y + hx * MIN_BLINK_ESCAPE_DISTANCE}, escapeBlinkCap);
+		const sideB = capBlinkDistance({x: position.x + hy * MIN_BLINK_ESCAPE_DISTANCE, y: position.y - hx * MIN_BLINK_ESCAPE_DISTANCE}, escapeBlinkCap);
+		return wallScore(sideA) >= wallScore(sideB) ? sideA : sideB;
+	}
+
+	const distance = distanceTo(position, enemy.position);
+	const urgentThreat = getMostUrgentThreat(threats);
+	const dodgeDirection = getDodgeDirectionForMovement(threats, position);
+	// Hard-homing incoming missile → can't be out-strafed; must blink or shield it.
+	// A lethal big hit (≥LETHAL_HIT_DAMAGE) is treated the same: never strafe-gamble a
+	// missile that would one-shot Hero, even if the dodge sim thinks it's dodgeable.
+	const hardHomingThreat =
+		urgentThreat !== null &&
+		urgentThreat.willHit &&
+		(urgentThreat.projectile.turnRate >= hardHomingTurn ||
+			urgentThreat.projectile.damage >= LETHAL_HIT_DAMAGE);
+
+	// HP-aware distance: ahead → fight closer, behind → kite at range
+	const hpDiff = health - enemy.health;
+	const isAggressive = hpDiff >= -aggressiveHPThreshold;
+	// --- OPPONENT CLASSIFICATION → counter by adjusting engagement distance ---
+	// Read the opponent's range/missile style from visible signals (no persistent
+	// state): how close they hold / whether they're closing, and their live missiles.
+	const toHeroX = position.x - enemy.position.x;
+	const toHeroY = position.y - enemy.position.y;
+	const toHeroMag = Math.hypot(toHeroX, toHeroY) || 1;
+	const enemyClosingRate = (enemy.velocity.x * toHeroX + enemy.velocity.y * toHeroY) / toHeroMag; // >0 = approaching
+	// There is exactly one enemy (1v1 duel) and EnemyState carries no id, so the
+	// opponent's live missiles are every in-flight projectile that isn't ours.
+	const myProjectileIds = new Set(myProjectiles.map((p) => p.id));
+	const enemyMissiles = projectiles.filter((p) => !myProjectileIds.has(p.id));
+	const enemyHoming = enemyMissiles.some((p) => p.turnRate >= 0.5);
+	const enemyFastStraight = enemyMissiles.some((p) => p.turnRate < 0.3 && p.speed >= 6);
+	// A monster missile (only the max-damage benchmark fires this big) one-shots Hero and
+	// its knockback (~330u, ignores shields) flings Hero into lava — so blink it (0 dmg +
+	// 0 knockback) when blink is up, else hold toward center and shield it from safety.
+	const lethalMissile = enemyMissiles.find((p) => p.damage >= LETHAL_HIT_DAMAGE) ?? null;
+	if (lethalMissile) oppModel.current.sawLethal = true;
+	const lethalShooter = oppModel.current.sawLethal;
+	// Identify the relentless-homer champions by their unique missile fingerprints (sticky):
+	// the SNIPER by its spd-12 shot; the advancing BERSERKER by its dmg≥14 + long-life
+	// (≥120 ticks) + hard-homing (turn≥0.8) shot (dmg distinguishes it from the dmg-12
+	// long-life casters Flamecaller/Bonemancer that Hero already beats). Both relentlessly
+	// connect during Hero's GCD, so both get the same anti-homer toolkit.
+	if (enemyMissiles.some((p) =>
+		p.speed >= SNIPER_MISSILE_SPEED ||
+		(p.damage >= 14 && p.remainingTicks >= 120 && p.turnRate >= 0.8))) oppModel.current.sawSniper = true;
+	const sawSniper = oppModel.current.sawSniper;
+	// REACTIVE DELEGATION — the adaptable answer to Hero's RPS hard-counters. If Hero is
+	// CLEARLY losing (failing to dent the enemy well into the match), its duelist strategy is
+	// hard-countered (Archlich/Archmage — Hero can't out-duel them). Switch to Spellshot,
+	// which beats BOTH 100%. The trigger is SELF-CORRECTING: it only fires when Hero is
+	// genuinely losing, which never happens vs the look-alikes Hero beats (Golem/Lich — Hero
+	// dents them early), so it can't regress them. Spellshot() is called unconditionally each
+	// tick (stable hook order) and only RETURNED once latched (sticky for the rest of match).
+	const spellshotAction = Spellshot();
+	const om2 = oppModel.current;
+	// Sticky: enemy is a turn-0.5 big homer (the Archlich/Golem/Lich/Archmage class) — NOT a
+	// melee/turn-1 bot (Spellshot loses to those, so we must never delegate vs them).
+	if (enemyMissiles.some((p) => p.damage >= 25 && p.turnRate >= 0.45 && p.turnRate <= 0.6)) om2.sawMidHomer = true;
+	// Latch to Spellshot ONLY when BOTH hold: (1) the enemy is that turn-0.5 big-homer class,
+	// and (2) Hero literally can't damage it — still near full HP deep into the match (dealt
+	// <~4). Among the class, only Archlich keeps its HP this high (Hero dents Golem/Lich/the
+	// Archmage-mirror well below); so this fires ONLY vs Archlich. Spellshot beats it 100%.
+	if (!om2.losingLatched && om2.sawMidHomer && tick > 700 && enemy.health > 56)
+	{
+		om2.losingLatched = true;
+	}
+	if (om2.losingLatched) return spellshotAction;
+
+	// MIRROR detection (sticky): the enemy keeps firing missiles with the EXACT config Hero
+	// just fired (same dmg/spd/turn). Uniquely the near-mirror — identical logic + identical
+	// inputs produce the same missile every exchange. Count ticks-with-a-match; ≥80 means it
+	// matched across more than one missile's flight (~60t each), ruling out a one-off
+	// coincidence (Golem/Lich fire turn-0.5 but don't track Hero's evolving config + timing).
+	if (lastMissileConfig && enemyMissiles.some((p) =>
+		Math.abs(p.damage - lastMissileConfig.damage) < 1.5 &&
+		Math.abs(p.turnRate - lastMissileConfig.turnRate) < 0.06 &&
+		Math.abs(p.speed - lastMissileConfig.speed) < 0.6)) om2.mirrorMatchTicks++;
+	const sawMirror = om2.mirrorMatchTicks >= 80;
+
+	// Counter by MISSILE TYPE first (it distinguishes ranged from melee even at close
+	// range, where distance alone can't): a fast-straight stabber is a melee threat —
+	// hold base distance so we're not in point-blank range; a homing caster/kiter — close
+	// in HARD to land missiles and pressure, even once we're already close. Distance is
+	// only a fallback when no missiles are visible yet.
+	let opponentOffset = 0;
+	if (sawMirror)
+	{
+		// MIRROR: hold ~Archmage's range instead of closing. Closing (the -190 branch below)
+		// is what diverges Hero's movement and costs it the even trade; holding keeps the
+		// geometry symmetric → draw rather than a snowball loss.
+		opponentOffset = 31;
+	}
+	else if (enemyFastStraight || enemyClosingRate > 0.3)
+	{
+		opponentOffset = 31; // melee stabber / charging aggressor → hold the OLD (farther) distance, avoid point-blank
+	}
+	else if (enemyHoming || distance > 430)
+	{
+		opponentOffset = -190; // caster / kiter → close in HARD (land missiles + pressure)
+	}
+
+	const effectiveTargetDistance = Math.max(120, Math.min(560, (isAggressive
+		? targetDistance - aggressiveDistanceOffset
+		: targetDistance + cautiousDistanceOffset) + opponentOffset));
+
+	const move = combatMove(
+		position,
+		enemy,
+		distance,
+		effectiveTargetDistance,
+		dodgeDirection,
+		tick,
+		strafeCyclePeriod,
+		strafeIntensity,
+		approachSpeed,
+		distanceDeadZone,
+		centerBias,
+	);
+	let safeMove = keepOffWalls(position, move);
+	// vs the max-damage benchmark: drift to arena center (while still casting/strafing) so
+	// Hero is already central when the monster missile lands — its ~330u shielded-hit
+	// knockback then can't reach lava. Only engages once a ≥50-dmg missile has been seen.
+	if (lethalShooter || sawSniper)
+	{
+		const center = (ARENA_MIN + ARENA_MAX) / 2;
+		const cdx = center - position.x;
+		const cdy = center - position.y;
+		const cdist = Math.hypot(cdx, cdy);
+		if (cdist > 70) safeMove = {x: cdx / cdist, y: cdy / cdist};
+	}
+	// === STEP 1: CHANNELING ===
+	if (status === 'channeling')
+	{
+		if (!urgentThreat || urgentThreat.ticksToImpact > shieldCancelThreshold)
+		{
+			return cancel().move(safeMove.x, safeMove.y);
+		}
+		return idle();
+	}
+
+	// === STEP 2: PROGRESSIVE CAST-CANCEL ===
+	if (
+		status === 'casting' &&
+    castingSpell === 'missile' &&
+    urgentThreat &&
+    (!urgentThreat.bestDodgeDirection || hardHomingThreat)
+	)
+	{
+		const remainingCast = ((castProgressData?.total) ?? 0) - ((castProgressData?.current) ?? 0);
+		const defenseTime =
+			blinkCooldown === 0
+				? RULES.BLINK_CAST_TIME
+				: RULES.SHIELD_CAST_TIME + SHIELD_BUFFER;
+		const willArriveInWindow =
+			urgentThreat.ticksToImpact <= remainingCast + RULES.GCD_DURATION + defenseTime;
+
+		if (willArriveInWindow)
+		{
+			const incomingDamage = urgentThreat.projectile.damage;
+			const castRatio = ((castProgressData?.current) ?? 0) / ((castProgressData?.total) ?? 1);
+
+			if (incomingDamage >= health || incomingDamage >= cancelHeavyDmg)
+			{
+				return cancel().move(safeMove.x, safeMove.y);
+			}
+			if (incomingDamage >= cancelMediumDmg && castRatio < cancelCastRatio)
+			{
+				return cancel().move(safeMove.x, safeMove.y);
+			}
+			// Cheap hard-homer: can't strafe it and it's below the damage thresholds,
+			// so abandon an early cast to free up a blink/shield rather than eat it.
+			if (hardHomingThreat && castRatio < cancelCastRatio)
+			{
+				return cancel().move(safeMove.x, safeMove.y);
+			}
+		}
+	}
+
+	// === LETHAL MISSILE — perpendicular-blink the instant blink is up (0 dmg AND 0
+	// knockback). Shielding a 60-dmg monster blocks the damage but NOT the ~330u
+	// knockback, which flings Hero into lava. A wider window than the normal blink-dodge:
+	// this hit WILL land and is the only thing that matters. (Only Doombringer fires ≥50.)
+	if (status === 'idle' && lethalMissile && blinkCooldown === 0)
+	{
+		const perp = blinkPerpendicularTo(lethalMissile);
+		return blink(perp.x, perp.y);
+	}
+
+	// === STEP 3: BLINK-DODGE — 100% damage avoidance (optimizer-controlled) ===
+	if (
+		preferBlinkDodge &&
+    status === 'idle' &&
+    urgentThreat &&
+    blinkCooldown === 0 &&
+    (!urgentThreat.bestDodgeDirection || shouldForceShield(urgentThreat) || hardHomingThreat) &&
+    urgentThreat.ticksToImpact >= RULES.BLINK_CAST_TIME &&
+    urgentThreat.ticksToImpact <= blinkWindowMax
+	)
+	{
+		// Hard-homing missile: blink perpendicular to its heading to break the lock
+		// (toward/away gets re-acquired). 0 damage vs a shield's ~10% leak.
+		if (hardHomingThreat)
+		{
+			const perp = blinkPerpendicularTo(urgentThreat.projectile);
+			return blink(perp.x, perp.y);
+		}
+		// Aggressive: blink toward enemy to dodge + close gap
+		// Defensive: blink away to dodge + increase distance
+		if (isAggressive && distance > effectiveTargetDistance)
+		{
+			const blinkTarget = getBlinkToDecreaseDistance(
+				position,
+				enemy.position,
+				projectiles,
+			);
+			if (blinkTarget)
+			{
+				const capped = capBlinkDistance(blinkTarget);
+				return blink(capped.x, capped.y);
+			}
+		}
+		const blinkTarget = getBlinkToIncreaseDistance(
+			position,
+			enemy.position,
+			projectiles,
+			MIN_BLINK_ESCAPE_DISTANCE,
+		);
+		if (blinkTarget)
+		{
+			const capped = capBlinkDistance(blinkTarget, escapeBlinkCap);
+			return blink(capped.x, capped.y);
+		}
+	}
+
+	// === STEP 4: BLINK ESCAPE — enemy too close ===
+	if (
+		status === 'idle' &&
+    distance < blinkEscapeDistance &&
+    blinkCooldown === 0 &&
+    (!urgentThreat || urgentThreat.bestDodgeDirection !== null)
+	)
+	{
+		const escapeTarget = getBlinkToIncreaseDistance(
+			position,
+			enemy.position,
+			projectiles,
+			MIN_BLINK_ESCAPE_DISTANCE,
+		);
+		if (escapeTarget)
+		{
+			const capped = capBlinkDistance(escapeTarget, escapeBlinkCap);
+			return blink(capped.x, capped.y);
+		}
+	}
+
+	// === STEP 5: SHIELD ===
+	if (
+		status === 'idle' &&
+    urgentThreat &&
+    (!urgentThreat.bestDodgeDirection || shouldForceShield(urgentThreat) || hardHomingThreat)
+	)
+	{
+		if (
+			urgentThreat.canBlockInTime &&
+      urgentThreat.ticksToStartShield <= SHIELD_BUFFER &&
+      (blinkCooldown > 0 || urgentThreat.ticksToImpact < 10)
+		)
+		{
+			return shield();
+		}
+	}
+
+	// === Preemptive shield — shield when enemy is casting a missile at close range ===
+	if (
+		status === 'idle' &&
+		distance < 300 &&
+		enemy.status === 'casting' &&
+		enemy.castingSpell === 'missile'
+	)
+	{
+		const remainingCast = (enemy.castDuration ?? 0) - (enemy.castProgress ?? 0);
+		const estimatedFlightTicks = distance / 8;
+		const ticksUntilHit = remainingCast + estimatedFlightTicks;
+
+		if (
+			ticksUntilHit >= RULES.SHIELD_CAST_TIME &&
+			ticksUntilHit < RULES.SHIELD_CAST_TIME + 15
+		)
+		{
+			return shield();
+		}
+	}
+
+	// === STEP 6: VULNERABILITY BLINK — gap-close during enemy cast/GCD ===
+	if (
+		status === 'idle' &&
+    blinkCooldown === 0 &&
+    isAggressive &&
+    distance > effectiveTargetDistance + blinkGapThreshold &&
+    (!urgentThreat || urgentThreat.bestDodgeDirection !== null)
+	)
+	{
+		const vulnerabilityTicks = getEnemyVulnerabilityTicks(enemy);
+		if (vulnerabilityTicks >= punishMinVulnerability)
+		{
+			const blinkTarget = getBlinkToDecreaseDistance(
+				position,
+				enemy.position,
+				projectiles,
+			);
+			if (blinkTarget)
+			{
+				const capped = capBlinkDistance(blinkTarget);
+				return blink(capped.x, capped.y);
+			}
+		}
+	}
+
+	// === STEP 7: OFFENSE ===
+	if (status === 'idle' && distance < 500)
+	{
+		// A lethal missile is inbound and blink is down — do NOT start a cast (we'd cancel
+		// it and lose the shield-timing race). Move toward arena center so the un-shieldable
+		// ~330u knockback can't fling Hero into lava; STEP 5 shields it from safety.
+		if (lethalMissile)
+		{
+			const center = (ARENA_MIN + ARENA_MAX) / 2;
+			const cdx = center - position.x;
+			const cdy = center - position.y;
+			const cmag = Math.hypot(cdx, cdy) || 1;
+			return moveAction(cdx / cmag, cdy / cmag);
+		}
+
+		const reposition = getPreCastReposition(position, enemy.position);
+		if (reposition) return moveAction(reposition.x, reposition.y);
+
+		const offenseDefenseTime =
+			blinkCooldown === 0
+				? RULES.BLINK_CAST_TIME
+				: RULES.SHIELD_CAST_TIME + SHIELD_BUFFER;
+		const enemyHP = Math.ceil(enemy.health);
+		// vs the identified sniper: cap missiles just under its >=25 force-shield threshold
+		// so they land FULL (small homers out-race its snipes) instead of being shielded to ~3.
+		const offenseMaxDamage = sawSniper ? Math.min(enemyHP, SNIPER_DAMAGE_CAP) : enemyHP;
+		const vulnerabilityTicks = getEnemyVulnerabilityTicks(enemy);
+
+		// --- FINISHER: enemy is one shot from death. Take the kill even into incoming
+		// fire (the match ends before their damage matters) — but ONLY if Hero survives
+		// every in-flight hit, so it can't suicide. Bypasses the attack-safety guard that
+		// otherwise forfeits won-by-a-hair races (e.g. enemy left at 1 HP while Hero defends).
+		if (enemyHP <= finisherEnemyHP)
+		{
+			const killConfig = fitMissileToBudget(MAX_CAST_BUDGET, distance, {
+				minTurnRate: distance < closeRangeStraightThreshold ? 0 : minTurnRate,
+				maxDamage: Math.max(enemyHP, MIN_USEFUL_DAMAGE),
+				lastMissileConfig: lastMissileConfig,
+			});
+			const incomingDmg = threats.filter((t) => t.willHit).reduce((s, t) => s + t.projectile.damage, 0);
+			if (killConfig && killConfig.damage >= enemyHP && health > incomingDmg)
+			{
+				const aimTarget =
+					killConfig.turnRate > 0
+						? enemy.position
+						: getLeadPosition(enemy.position, enemy.velocity, killConfig.speed, position);
+				return missile(killConfig, killConfig.turnRate > 0 ? HomingAI : StraightAI, angleTo(position, aimTarget)).move(safeMove.x, safeMove.y);
+			}
+		}
+
+		// vs the sniper: only START a cast in its post-fire GCD window (enemy.status
+		// 'gcd_locked'). Then our own GCD ends BEFORE its next snipe (~one full cast away),
+		// leaving us idle to DODGE that snipe — the snipes are turn-0.3 dodgeable; we only
+		// eat them while GCD-locked. Otherwise hold and dodge. (Finisher above bypasses this.)
+		if (sawSniper && enemy.status !== 'gcd_locked')
+		{
+			return moveAction(safeMove.x, safeMove.y);
+		}
+
+		// --- PUNISH MODE: range-adaptive missiles during vulnerability ---
+		// Skipped vs the sniper: its window-clamped budget makes short missiles that fall
+		// short of / can't chase the blinking target. STANDARD below fires a full-budget homer.
+		if (!sawSniper && vulnerabilityTicks >= punishMinVulnerability)
+		{
+			const flightTimeEstimate = distance / flightTimeDivisor;
+			const punishBudget = vulnerabilityTicks - flightTimeEstimate;
+			const nextThreatTime = urgentThreat?.ticksToImpact ?? Infinity;
+			const safeBudget = nextThreatTime - RULES.GCD_DURATION - offenseDefenseTime;
+			const effectiveBudget = Math.min(
+				punishBudget,
+				safeBudget,
+				MAX_CAST_BUDGET,
+			);
+
+			if (effectiveBudget > 0)
+			{
+				// Close range → straight for max damage, far → light homing; vs the sniper
+				// force real homing so the missile chases its strafing/blinking dodge.
+				const punishTurnRate = sawSniper ? 0.5 : (distance < closeRangeStraightThreshold ? 0 : 0.2);
+				const config = fitMissileToBudget(effectiveBudget, distance, {
+					minTurnRate: punishTurnRate,
+					maxDamage: offenseMaxDamage,
+					lastMissileConfig: lastMissileConfig,
+				});
+
+				if (config && config.damage >= MIN_USEFUL_DAMAGE)
+				{
+					const castTime = getMissileCastTime(config, lastMissileConfig);
+					const actualFlight = distance / config.speed;
+					// During the enemy's GCD they can't shield, and after it ends they still
+					// need SHIELD_CAST_TIME to channel one — so a missile landing within
+					// gcd + SHIELD_CAST_TIME is genuinely unblockable (matchup-independent).
+					const punishWindow =
+						enemy.status === 'gcd_locked'
+							? vulnerabilityTicks + RULES.SHIELD_CAST_TIME
+							: vulnerabilityTicks;
+
+					if (
+						castTime + actualFlight < punishWindow &&
+            isSafeToAttack(threats, castTime)
+					)
+					{
+						const aimTarget =
+							config.turnRate > 0
+								? enemy.position
+								: getLeadPosition(
+									enemy.position,
+									enemy.velocity,
+									config.speed,
+									position,
+								);
+						return missile(config, config.turnRate > 0 ? HomingAI : StraightAI, angleTo(position, aimTarget)).move(safeMove.x, safeMove.y);
+					}
+				}
+			}
+		}
+
+		// --- STANDARD MODE: range-adaptive missiles ---
+		const nextThreatTime = urgentThreat?.ticksToImpact ?? Infinity;
+		const safeBudget = nextThreatTime - RULES.GCD_DURATION - offenseDefenseTime;
+		// vs the sniper: full-budget (long-lived, connects on the strafing target) homing.
+		const budgetTicks = sawSniper ? MAX_CAST_BUDGET : Math.min(safeBudget, MAX_CAST_BUDGET);
+
+		// Adapt turn rate to distance: close → straight, far → homing; vs the sniper force homing.
+		const effectiveMinTurnRate = sawSniper
+			? Math.max(minTurnRate, 0.5)
+			: (distance < closeRangeStraightThreshold ? 0 : minTurnRate);
+		const minDmg = Math.min(MIN_USEFUL_DAMAGE, enemyHP);
+		// vs the sniper: provision extra range — it strafes/blinks (~300u) away during our
+		// cast + the missile's flight, so the homer needs the LIFE to chase, not fall short.
+		const fitDistance = sawSniper ? distance + 300 : distance;
+		let config = fitMissileToBudget(budgetTicks, fitDistance, {
+			minTurnRate: effectiveMinTurnRate,
+			maxDamage: offenseMaxDamage,
+			lastMissileConfig: lastMissileConfig,
+		});
+
+		if (config && config.damage >= minDmg)
+		{
+			const actualCastTime = getMissileCastTime(config, lastMissileConfig);
+			if (isSafeToAttack(threats, actualCastTime))
+			{
+				return missile(config, config.turnRate > 0 ? HomingAI : StraightAI, angleTo(position, enemy.position)).move(safeMove.x, safeMove.y);
+			}
+		}
+
+		// Fallback: fire bigger missile, accept incoming hit — but only if no undodgeable threat
+		if (!config || config.damage < minDmg)
+		{
+			config = fitMissileToBudget(MAX_CAST_BUDGET, fitDistance, {
+				minTurnRate: effectiveMinTurnRate,
+				maxDamage: offenseMaxDamage,
+				lastMissileConfig: lastMissileConfig,
+			});
+			if (config && (!urgentThreat || urgentThreat.bestDodgeDirection !== null))
+			{
+				return missile(config, config.turnRate > 0 ? HomingAI : StraightAI, angleTo(position, enemy.position)).move(safeMove.x, safeMove.y);
+			}
+		}
+	}
+
+	return moveAction(safeMove.x, safeMove.y);
+}