@vibemancer/core 0.1.0

package/src/hooks/state-hooks.ts

@@ -0,0 +1,354 @@
+/**
+ * VIBEMANCER - STATE HOOKS
+ *
+ * React-style hooks for reading game state.
+ * These handle the "subconscious" perception that humans do instinctively.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Velocity:   units per tick on each axis (player max speed = 1 u/t)
+ *   Health:     hit points (max 60)
+ *   Ticks:      game ticks (10ms each, 100/sec). Divide by 100 for seconds.
+ *   Shield:     block multiplier 0.0-0.9 (0.9 = blocks 90% damage)
+ */
+
+import {Position, Velocity, ProjectileState} from '../types.js';
+import {getBotContext, useMemo} from '../engine/hooks-runtime.js';
+import {SHIELD_MAX_BLOCK, SHIELD_DECAY_PER_SECOND, SHIELD_MIN_BLOCK, TICKS_PER_SECOND} from '../rules.js';
+import type {EnemyState, AnalyzedThreat} from './types.js';
+import {analyzeThreats} from './threat-analysis.js';
+
+// ============================================================
+// SELF STATE HOOKS
+// ============================================================
+
+/**
+ * Get your current health (0-60). Wizard dies at 0.
+ */
+export function useHealth(): number
+{
+	return getBotContext().health;
+}
+
+/**
+ * Get your current position as {x, y} in world coordinates (0-800).
+ * Position is clamped to [5, 795] (arena bounds minus wizard radius).
+ */
+export function usePosition(): Position
+{
+	const ctx = getBotContext();
+	return {x: ctx.position.x, y: ctx.position.y};
+}
+
+/**
+ * Get your current velocity as {x, y} in units/tick.
+ * Max magnitude is 1 u/t when idle, 0.5 u/t when casting, 0 when channeling shield.
+ */
+export function useVelocity(): Velocity
+{
+	const ctx = getBotContext();
+	return {x: ctx.velocity.x, y: ctx.velocity.y};
+}
+
+/**
+ * Get your current status:
+ * - 'idle':        free to act
+ * - 'casting':     casting a spell (missile or blink). Can move at 50% speed.
+ * - 'channeling':  channeling shield. Cannot move. Cancel anytime with cancel().
+ * - 'gcd_locked':  global cooldown after spell. Can move at full speed, but cannot cast.
+ */
+export function useStatus(): 'idle' | 'casting' | 'channeling' | 'gcd_locked'
+{
+	return getBotContext().state;
+}
+
+/**
+ * Get ticks until you can start a new spell.
+ *
+ * Returns 0 when idle or channeling (shield can be canceled immediately).
+ * During casting: remaining cast ticks. During GCD: remaining GCD ticks.
+ *
+ * Note: 100 ticks = 1 second.
+ */
+export function useTicksUntilReady(): number
+{
+	const ctx = getBotContext();
+
+	switch (ctx.state)
+	{
+		case 'idle':
+			return 0;
+		case 'casting':
+			// Remaining cast time
+			if (ctx.castDuration !== undefined && ctx.castProgress !== undefined)
+			{
+				return ctx.castDuration - ctx.castProgress;
+			}
+			return 0;
+		case 'channeling':
+			// Can cancel anytime, so 0
+			return 0;
+		case 'gcd_locked':
+			return ctx.gcdRemaining ?? 0;
+		default:
+			return 0;
+	}
+}
+
+/**
+ * Get current shield block multiplier.
+ *
+ * Returns 0 if not channeling shield.
+ * Returns 0.3-0.9 if channeling: starts at 0.9 (blocks 90%), decays by 0.2/sec,
+ * minimum 0.3 (blocks 30%). The remaining damage gets through:
+ * actualDamage = incomingDamage × (1 - shieldStrength).
+ */
+export function useShieldStrength(): number
+{
+	const ctx = getBotContext();
+
+	if (ctx.state !== 'channeling' || ctx.channelingSpell !== 'shield')
+	{
+		return 0;
+	}
+
+	// Calculate shield strength based on channel duration
+	const channelDuration = ctx.channelDuration ?? 0;
+	const decayPerTick = SHIELD_DECAY_PER_SECOND / TICKS_PER_SECOND;
+	const strength = SHIELD_MAX_BLOCK - (channelDuration * decayPerTick);
+	return Math.max(SHIELD_MIN_BLOCK, strength);
+}
+
+/**
+ * Get blink cooldown remaining in ticks. Returns 0 if ready to blink.
+ *
+ * Cooldown scales with distance used:
+ * - 100 units → ~100 ticks (1s)
+ * - 300 units (max range) → 2000 ticks (20s)
+ *
+ * Note: 100 ticks = 1 second.
+ */
+export function useBlinkCooldown(): number
+{
+	return getBotContext().blinkCooldown;
+}
+
+/**
+ * Get currently casting spell, or null if not casting.
+ * Returns 'missile', 'shield', or 'blink'.
+ */
+export function useCastingSpell(): 'missile' | 'shield' | 'blink' | null
+{
+	const ctx = getBotContext();
+	if (ctx.state !== 'casting')
+	{
+		return null;
+	}
+	return ctx.castingSpell ?? null;
+}
+
+/**
+ * Get cast progress as {current, total} in ticks, or null if not casting.
+ *
+ * current = ticks elapsed, total = ticks needed. When current >= total, spell fires.
+ * Note: 100 ticks = 1 second.
+ */
+export function useCastProgress(): {current: number; total: number} | null
+{
+	const ctx = getBotContext();
+	if (ctx.state !== 'casting')
+	{
+		return null;
+	}
+	if (ctx.castProgress === undefined || ctx.castDuration === undefined)
+	{
+		return null;
+	}
+	return {current: ctx.castProgress, total: ctx.castDuration};
+}
+
+// ============================================================
+// ENEMY STATE HOOK
+// ============================================================
+
+/**
+ * Get enemy wizard state.
+ *
+ * Returns position, velocity, health, status, casting spell, and shield strength.
+ * Note: you cannot see the enemy's missile configs or exact cooldown timers —
+ * only their status and what's visible on the field.
+ */
+export function useEnemy(): EnemyState
+{
+	const ctx = getBotContext();
+	const enemy = ctx.enemies[0];
+
+	if (!enemy)
+	{
+		// No enemy - return default state
+		return {
+			position: {x: 0, y: 0},
+			velocity: {x: 0, y: 0},
+			health: 0,
+			status: 'idle',
+			castingSpell: null,
+			shieldStrength: 0,
+		};
+	}
+
+	// Calculate enemy shield strength
+	let shieldStrength = 0;
+	if (enemy.state === 'channeling' && enemy.channelingSpell === 'shield')
+	{
+		const channelDuration = enemy.channelDuration ?? 0;
+		const decayPerTick = SHIELD_DECAY_PER_SECOND / TICKS_PER_SECOND;
+		shieldStrength = Math.max(SHIELD_MIN_BLOCK, SHIELD_MAX_BLOCK - (channelDuration * decayPerTick));
+	}
+
+	return {
+		position: {x: enemy.position.x, y: enemy.position.y},
+		velocity: {x: enemy.velocity.x, y: enemy.velocity.y},
+		health: enemy.health,
+		status: enemy.state,
+		castingSpell: enemy.state === 'casting' ? (enemy.castingSpell ?? null) : null,
+		shieldStrength,
+	};
+}
+
+// ============================================================
+// PROJECTILE HOOKS
+// ============================================================
+
+/**
+ * Get all your active (in-flight) projectiles.
+ * Each has position, rotation (degrees), speed (u/t), turnRate, remainingTicks.
+ */
+export function useMyProjectiles(): ProjectileState[]
+{
+	return getBotContext().myProjectiles;
+}
+
+// ============================================================
+// COMBAT TRACKING HOOKS
+// ============================================================
+
+/**
+ * Get total damage you've dealt this match.
+ */
+export function useDamageDealt(): number
+{
+	return getBotContext().damageDealt;
+}
+
+/**
+ * Get total damage you've taken this match.
+ */
+export function useDamageTaken(): number
+{
+	return getBotContext().damageTaken;
+}
+
+/**
+ * Get the tick number when you last took damage. Returns 0 if never hit.
+ * Compare with useTick() to get ticks since last hit.
+ */
+export function useLastHitTick(): number
+{
+	return getBotContext().lastHitTick;
+}
+
+// ============================================================
+// ARENA HOOKS
+// ============================================================
+
+/**
+ * Get arena dimensions. Default: {width: 800, height: 800}.
+ * Wizards are clamped to [5, 795] on each axis (radius = 5).
+ */
+export function useArenaSize(): {width: number; height: number}
+{
+	const ctx = getBotContext();
+	return {width: ctx.arenaWidth, height: ctx.arenaHeight};
+}
+
+/**
+ * Get current game tick (starts at 0, increments each tick).
+ * 100 ticks = 1 second. Match ends at 30,000 ticks (5 minutes).
+ */
+export function useTick(): number
+{
+	return getBotContext().tick;
+}
+
+// ============================================================
+// THREAT ANALYSIS HOOKS
+// ============================================================
+
+/**
+ * Get analyzed threats from all incoming enemy projectiles.
+ * Sorted by ticksToImpact (soonest first). Only includes missiles within 500 units
+ * or that are predicted to hit.
+ *
+ * Each threat includes:
+ * - ticksToImpact: ticks until hit (Infinity if will miss)
+ * - willHit: true if missile hits your current position
+ * - canDodgeLeft/Right: whether strafing perpendicular to missile heading works
+ * - canOutrun: whether moving away from missile escapes it
+ * - bestDodgeDirection: {x, y} unit vector to dodge optimally, or null if undodgeable
+ * - canBlockInTime: whether you can raise shield before impact
+ * - ticksToStartShield: when to START channeling shield to block in time
+ */
+export function useThreats(): AnalyzedThreat[]
+{
+	const ctx = getBotContext();
+	const ticksUntilReady = useTicksUntilReady();
+
+	// Memoize to avoid recalculating every call
+	return useMemo(() =>
+	{
+		return analyzeThreats(
+			ctx.position,
+			ctx.projectiles,
+			ctx.myProjectiles,
+			ticksUntilReady,
+		);
+	}, [ctx.projectiles, ctx.myProjectiles, ctx.position.x, ctx.position.y, ticksUntilReady]);
+}
+
+/**
+ * Get the most imminent threat, or null if no threats.
+ * Shorthand for useThreats()[0].
+ */
+export function useClosestThreat(): AnalyzedThreat | null
+{
+	const threats = useThreats();
+	return threats[0] ?? null;
+}
+
+/**
+ * Get your missiles analyzed from the enemy's perspective.
+ * Useful to predict when enemy will shield/dodge your attacks.
+ */
+export function useMyThreatsToEnemy(): AnalyzedThreat[]
+{
+	const ctx = getBotContext();
+	const enemy = ctx.enemies[0];
+
+	if (!enemy)
+	{
+		return [];
+	}
+
+	// Memoize to avoid recalculating every call
+	return useMemo(() =>
+	{
+		// Analyze from enemy's perspective
+		// Pass empty array for "enemy's own projectiles" since we're analyzing our missiles as threats TO them
+		return analyzeThreats(
+			enemy.position,
+			ctx.myProjectiles, // Our projectiles are their threats
+			[], // Enemy has no "own projectiles" in this context
+			0, // We don't know enemy's ticksUntilReady
+		);
+	}, [ctx.myProjectiles, enemy.position.x, enemy.position.y]);
+}

package/src/hooks/threat-analysis.ts

@@ -0,0 +1,365 @@
+/**
+ * VIBEMANCER - THREAT ANALYSIS
+ *
+ * Pre-computes threat information for incoming projectiles.
+ * This handles the "subconscious" perception of missile trajectories.
+ */
+
+import {Position, ProjectileState} from '../types.js';
+import {
+	COLLISION_RADIUS,
+	MISSILE_BASE_RADIUS,
+	MISSILE_RADIUS_PER_DAMAGE,
+	MOVE_SPEED,
+	SHIELD_CAST_TIME,
+	ARENA_WIDTH,
+	ARENA_HEIGHT,
+	ARENA_WATER_BUFFER,
+} from '../rules.js';
+import {distanceTo} from '../utils/distance.js';
+import {angleTo, normalizeAngle, angleDiff} from '../utils/angles.js';
+import type {AnalyzedThreat} from './types.js';
+
+// Maximum distance at which a missile is still tracked as a potential threat
+// (even if simulation says it will miss — homing missiles can change course)
+const THREAT_RELEVANCE_DISTANCE = 500;
+
+/**
+ * Analyze all threats from enemy projectiles.
+ *
+ * @param myPos - Current position of the wizard
+ * @param projectiles - All projectiles in the game
+ * @param myProjectiles - Only the bot's own projectiles (used for filtering)
+ * @param ticksUntilReady - Ticks until wizard can start a new action
+ * @returns Array of analyzed threats sorted by ticksToImpact (soonest first)
+ */
+export function analyzeThreats(
+	myPos: Position,
+	projectiles: ProjectileState[],
+	myProjectiles: ProjectileState[],
+	ticksUntilReady: number,
+): AnalyzedThreat[]
+{
+	// Filter to enemy projectiles by excluding our own
+	const myProjectileIds = new Set(myProjectiles.map((p) => p.id));
+	const enemyProjectiles = projectiles.filter((p) => !myProjectileIds.has(p.id));
+
+	// Analyze each projectile
+	const threats: AnalyzedThreat[] = [];
+
+	for (const projectile of enemyProjectiles)
+	{
+		const analysis = analyzeOneThreat(myPos, projectile, ticksUntilReady);
+		// Only include if it will hit or missile is within reasonable distance
+		const missileDistance = Math.sqrt(
+			(projectile.position.x - myPos.x) ** 2 +
+			(projectile.position.y - myPos.y) ** 2,
+		);
+		if (analysis.willHit || missileDistance < THREAT_RELEVANCE_DISTANCE)
+		{
+			threats.push(analysis);
+		}
+	}
+
+	// Sort by ticksToImpact (soonest first)
+	threats.sort((a, b) => a.ticksToImpact - b.ticksToImpact);
+
+	return threats;
+}
+
+/**
+ * Analyze a single projectile threat.
+ */
+function analyzeOneThreat(
+	targetPos: Position,
+	projectile: ProjectileState,
+	ticksUntilReady: number,
+): AnalyzedThreat
+{
+	// Calculate collision radius
+	const missileRadius = MISSILE_BASE_RADIUS + projectile.damage * MISSILE_RADIUS_PER_DAMAGE;
+	const collisionDist = COLLISION_RADIUS + missileRadius;
+
+	// Dodge simulation uses a larger collision distance to account for swept circle collision.
+	// The real game checks the entire missile path each tick (swept), but the simulation only
+	// checks endpoints. Adding half the missile speed compensates for this gap.
+	const dodgeCollisionDist = collisionDist + projectile.speed * 0.5;
+
+	// Simulate missile trajectory toward stationary target
+	const {willHit, ticksToImpact} = simulateMissileToTarget(
+		projectile,
+		targetPos,
+		collisionDist,
+	);
+
+	// Only simulate dodges for missiles that will actually hit (saves ~75% simulation work)
+	let canDodgeLeft = true;
+	let canDodgeRight = true;
+	let canOutrun = true;
+	let bestDodgeDirection: Position | null = null;
+
+	if (willHit)
+	{
+		canDodgeLeft = simulateDodge(projectile, targetPos, 'left', dodgeCollisionDist);
+		canDodgeRight = simulateDodge(projectile, targetPos, 'right', dodgeCollisionDist);
+		canOutrun = simulateDodge(projectile, targetPos, 'away', dodgeCollisionDist);
+
+		bestDodgeDirection = calculateBestDodgeDirection(
+			projectile,
+			targetPos,
+			canDodgeLeft,
+			canDodgeRight,
+			canOutrun,
+		);
+	}
+
+	// Calculate shield timing
+	// Can block if: ticksUntilReady + shield cast time < ticksToImpact
+	const canBlockInTime = ticksToImpact > ticksUntilReady + SHIELD_CAST_TIME + 1;
+
+	// When to start casting shield (leave 1 tick buffer)
+	const ticksToStartShield = Math.max(0, ticksToImpact - SHIELD_CAST_TIME - 1);
+
+	return {
+		id: projectile.id,
+		projectile,
+		ticksToImpact,
+		willHit,
+		canDodgeLeft,
+		canDodgeRight,
+		canOutrun,
+		bestDodgeDirection,
+		canBlockInTime,
+		ticksToStartShield,
+	};
+}
+
+/**
+ * Simulate a missile moving toward a stationary target.
+ * Accounts for homing (turn rate) and expiration.
+ */
+function simulateMissileToTarget(
+	projectile: ProjectileState,
+	targetPos: Position,
+	collisionDist: number,
+): {willHit: boolean; ticksToImpact: number}
+{
+	let pos = {...projectile.position};
+	let rotation = projectile.rotation;
+	const maxTicks = projectile.remainingTicks;
+	const speed = projectile.speed;
+	const turnRate = projectile.turnRate;
+
+	for (let tick = 1; tick <= maxTicks; tick++)
+	{
+		// Apply homing (turn toward target)
+		if (turnRate > 0)
+		{
+			const desiredAngle = angleTo(pos, targetPos);
+			const diff = angleDiff(rotation, desiredAngle);
+			const maxTurn = turnRate;
+
+			if (Math.abs(diff) <= maxTurn)
+			{
+				rotation = desiredAngle;
+			}
+			else
+			{
+				rotation = normalizeAngle(rotation + Math.sign(diff) * maxTurn);
+			}
+		}
+
+		// Move forward
+		const rad = rotation * (Math.PI / 180);
+		pos = {
+			x: pos.x + Math.cos(rad) * speed,
+			y: pos.y + Math.sin(rad) * speed,
+		};
+
+		// Check if missile is out of bounds (with water buffer)
+		if (isOutOfBounds(pos))
+		{
+			return {willHit: false, ticksToImpact: Infinity};
+		}
+
+		// Check collision
+		const dist = distanceTo(pos, targetPos);
+		if (dist <= collisionDist)
+		{
+			return {willHit: true, ticksToImpact: tick};
+		}
+	}
+
+	// Missile expired without hitting
+	return {willHit: false, ticksToImpact: Infinity};
+}
+
+/**
+ * Simulate a dodge attempt.
+ * Returns true if the dodge avoids the missile.
+ */
+function simulateDodge(
+	projectile: ProjectileState,
+	startPos: Position,
+	direction: 'left' | 'right' | 'away',
+	collisionDist: number,
+): boolean
+{
+	// Calculate dodge direction vector
+	const dodgeDir = getDodgeDirection(projectile, startPos, direction);
+
+	// If we can't determine a dodge direction, fail
+	if (dodgeDir.x === 0 && dodgeDir.y === 0)
+	{
+		return false;
+	}
+
+	let targetPos = {...startPos};
+	let missilePos = {...projectile.position};
+	let missileRotation = projectile.rotation;
+	const maxTicks = projectile.remainingTicks;
+	const speed = projectile.speed;
+	const turnRate = projectile.turnRate;
+
+	for (let tick = 1; tick <= maxTicks; tick++)
+	{
+		// Move target
+		const newX = targetPos.x + dodgeDir.x * MOVE_SPEED;
+		const newY = targetPos.y + dodgeDir.y * MOVE_SPEED;
+
+		// Clamp to arena bounds
+		targetPos = {
+			x: Math.max(COLLISION_RADIUS, Math.min(ARENA_WIDTH - COLLISION_RADIUS, newX)),
+			y: Math.max(COLLISION_RADIUS, Math.min(ARENA_HEIGHT - COLLISION_RADIUS, newY)),
+		};
+
+		// Apply missile homing toward new target position
+		if (turnRate > 0)
+		{
+			const desiredAngle = angleTo(missilePos, targetPos);
+			const diff = angleDiff(missileRotation, desiredAngle);
+			const maxTurn = turnRate;
+
+			if (Math.abs(diff) <= maxTurn)
+			{
+				missileRotation = desiredAngle;
+			}
+			else
+			{
+				missileRotation = normalizeAngle(missileRotation + Math.sign(diff) * maxTurn);
+			}
+		}
+
+		// Move missile
+		const rad = missileRotation * (Math.PI / 180);
+		missilePos = {
+			x: missilePos.x + Math.cos(rad) * speed,
+			y: missilePos.y + Math.sin(rad) * speed,
+		};
+
+		// Check if missile is out of bounds
+		if (isOutOfBounds(missilePos))
+		{
+			return true; // Dodged - missile left arena
+		}
+
+		// Check collision
+		const dist = distanceTo(missilePos, targetPos);
+		if (dist <= collisionDist)
+		{
+			return false; // Got hit while dodging
+		}
+	}
+
+	// Missile expired without hitting
+	return true;
+}
+
+/**
+ * Get the dodge direction vector based on direction type.
+ */
+function getDodgeDirection(
+	projectile: ProjectileState,
+	targetPos: Position,
+	direction: 'left' | 'right' | 'away',
+): Position
+{
+	// Get missile direction vector
+	const missileAngleRad = projectile.rotation * (Math.PI / 180);
+	const missileDir = {
+		x: Math.cos(missileAngleRad),
+		y: Math.sin(missileAngleRad),
+	};
+
+	switch (direction)
+	{
+		case 'left':
+			// Perpendicular to missile direction (left = counter-clockwise)
+			return {x: missileDir.y, y: -missileDir.x};
+
+		case 'right':
+			// Perpendicular to missile direction (right = clockwise)
+			return {x: -missileDir.y, y: missileDir.x};
+
+		case 'away':
+		{
+			// Away from missile current position
+			const dx = targetPos.x - projectile.position.x;
+			const dy = targetPos.y - projectile.position.y;
+			const len = Math.sqrt(dx * dx + dy * dy);
+			if (len === 0) return {x: 0, y: 0};
+			return {x: dx / len, y: dy / len};
+		}
+
+		default:
+			return {x: 0, y: 0};
+	}
+}
+
+/**
+ * Calculate the best dodge direction based on available options.
+ */
+function calculateBestDodgeDirection(
+	projectile: ProjectileState,
+	targetPos: Position,
+	canDodgeLeft: boolean,
+	canDodgeRight: boolean,
+	canOutrun: boolean,
+): Position | null
+{
+	// Prefer sidestep over outrunning (faster result)
+	if (canDodgeLeft && canDodgeRight)
+	{
+		// Both sides work - pick the one closer to where we want to be
+		// For simplicity, just return left
+		return getDodgeDirection(projectile, targetPos, 'left');
+	}
+	else if (canDodgeLeft)
+	{
+		return getDodgeDirection(projectile, targetPos, 'left');
+	}
+	else if (canDodgeRight)
+	{
+		return getDodgeDirection(projectile, targetPos, 'right');
+	}
+	else if (canOutrun)
+	{
+		return getDodgeDirection(projectile, targetPos, 'away');
+	}
+
+	// No dodge available
+	return null;
+}
+
+/**
+ * Check if a position is out of bounds (past the water buffer).
+ */
+function isOutOfBounds(pos: Position): boolean
+{
+	return (
+		pos.x < -ARENA_WATER_BUFFER ||
+		pos.x > ARENA_WIDTH + ARENA_WATER_BUFFER ||
+		pos.y < -ARENA_WATER_BUFFER ||
+		pos.y > ARENA_HEIGHT + ARENA_WATER_BUFFER
+	);
+}