@vibemancer/core 0.1.0

package/src/utils/combat.ts

@@ -0,0 +1,279 @@
+/**
+ * VIBEMANCER - COMBAT UTILITIES
+ *
+ * Utilities for combat calculations.
+ */
+
+import {Position, Velocity, MissileConfig} from '../types.js';
+import {
+	calculateMissileCastTime,
+	calculateWarmupMultiplier,
+	validateMissileConfig,
+	TICKS_PER_SECOND,
+	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,
+	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.
+ */
+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.
+	// Negative turnRate = anti-homing (turns away from target) but cheaper cast time.
+	const templates: [number, number][] = [
+		[7, -1],  // Fast anti-homing: cheapest cast, curves away from target
+		[7, -0.5],// Fast light anti-homing
+		[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;
+		// Minimum duration to reach target (with 20% margin for homing curve)
+		const margin = turnRate > 0 ? 1.2 : 1.05;
+		const minDurationTicks = Math.max(
+			MISSILE_MIN_DURATION,
+			Math.ceil(distance * margin / speed),
+		);
+		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;
+}

package/src/utils/distance.ts

@@ -0,0 +1,21 @@
+import {Position} from '../types.js';
+
+/**
+ * Calculate the distance between two points.
+ */
+export function distanceTo(a: Position, b: Position): number
+{
+	const dx = b.x - a.x;
+	const dy = b.y - a.y;
+	return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * Check if two points are within a certain range of each other.
+ */
+export function inRange(a: Position, b: Position, range: number): boolean
+{
+	const dx = b.x - a.x;
+	const dy = b.y - a.y;
+	return (dx * dx + dy * dy) <= range * range;
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from './distance.js';
+export * from './angles.js';
+export * from './movement.js';
+export * from './targeting.js';
+export * from './random.js';
+export * from './spatial.js';
+export * from './combat.js';

package/src/utils/movement.ts

@@ -0,0 +1,108 @@
+import {Position, Velocity} from '../types.js';
+import {normalizeAngle} from './angles.js';
+
+/**
+ * Get the position after moving a certain distance in a direction.
+ */
+export function moveInDirection(position: Position, angle: number, distance: number): Position
+{
+	const radians = angle * (Math.PI / 180);
+	return {
+		x: position.x + Math.cos(radians) * distance,
+		y: position.y + Math.sin(radians) * distance,
+	};
+}
+
+/**
+ * Predict the position after N ticks given current velocity.
+ */
+export function predictPosition(position: Position, velocity: Velocity, ticks: number): Position
+{
+	return {
+		x: position.x + velocity.x * ticks,
+		y: position.y + velocity.y * ticks,
+	};
+}
+
+/**
+ * Calculate the intercept angle for a target moving at a certain velocity.
+ * Returns null if no intercept solution exists.
+ */
+export function interceptAngle(
+	shooterPosition: Position,
+	targetPosition: Position,
+	targetVelocity: Velocity,
+	projectileSpeed: number,
+): number | null
+{
+	const dx = targetPosition.x - shooterPosition.x;
+	const dy = targetPosition.y - shooterPosition.y;
+
+	const vx = targetVelocity.x;
+	const vy = targetVelocity.y;
+
+	const a = vx * vx + vy * vy - projectileSpeed * projectileSpeed;
+	const b = 2 * (vx * dx + vy * dy);
+	const c = dx * dx + dy * dy;
+
+	let t: number | null = null;
+
+	// Handle the linear case when a is approximately zero
+	// This happens when |targetVelocity| === projectileSpeed
+	if (Math.abs(a) < 1e-10)
+	{
+		// Linear equation: b*t + c = 0 => t = -c/b
+		if (Math.abs(b) < 1e-10)
+		{
+			// No solution possible
+			return null;
+		}
+		const linearT = -c / b;
+		if (linearT > 0)
+		{
+			t = linearT;
+		}
+	}
+	else
+	{
+		// Quadratic case
+		const discriminant = b * b - 4 * a * c;
+
+		if (discriminant < 0)
+		{
+			return null;
+		}
+
+		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 (t === null)
+	{
+		return null;
+	}
+
+	const interceptPos = {
+		x: targetPosition.x + vx * t,
+		y: targetPosition.y + vy * t,
+	};
+
+	const dx2 = interceptPos.x - shooterPosition.x;
+	const dy2 = interceptPos.y - shooterPosition.y;
+
+	return normalizeAngle(Math.atan2(dy2, dx2) * (180 / Math.PI));
+}

package/src/utils/random.ts

@@ -0,0 +1,65 @@
+/**
+ * Seeded PRNG utilities for deterministic randomness.
+ *
+ * Each entity (wizard, missile) gets its own random sequence that:
+ * - Is deterministic: same seed = same sequence
+ * - Is isolated: one entity's calls don't affect another's
+ * - Advances state: each call produces a different value
+ */
+
+const MAX_INT = 0x7fffffff;
+
+/**
+ * Combine two seeds into one using a simple hash.
+ */
+export function hashCombine(a: number, b: number): number
+{
+	// Simple hash combining two integers
+	let hash = a;
+	hash = ((hash << 5) + hash) ^ b;
+	return hash & MAX_INT;
+}
+
+/**
+ * Advance the random state using a Linear Congruential Generator.
+ * Parameters from glibc (widely tested).
+ */
+export function nextRandom(state: number): number
+{
+	return (state * 1103515245 + 12345) & MAX_INT;
+}
+
+/**
+ * Create a seeded random number generator.
+ * Returns a function that produces values in [0, 1) and advances internal state.
+ */
+export function createRandom(seed: number): () => number
+{
+	let state = seed & MAX_INT;
+
+	return (): number =>
+	{
+		state = nextRandom(state);
+		return state / MAX_INT;
+	};
+}
+
+/**
+ * Create a deterministic seed for an entity based on match seed, entity ID, and tick.
+ * This ensures reproducibility: same match + same entity + same tick = same random sequence.
+ */
+export function createEntitySeed(matchSeed: number, entityId: string, tick: number): number
+{
+	// Hash the entity ID string into a number
+	let entityHash = 0;
+	for (let i = 0; i < entityId.length; i++)
+	{
+		entityHash = ((entityHash << 5) + entityHash) ^ entityId.charCodeAt(i);
+	}
+
+	// Combine match seed, entity hash, and tick
+	let combined = hashCombine(matchSeed, entityHash & MAX_INT);
+	combined = hashCombine(combined, tick);
+
+	return combined;
+}

package/src/utils/spatial.ts

@@ -0,0 +1,63 @@
+/**
+ * VIBEMANCER - SPATIAL UTILITIES
+ *
+ * Direction vectors and arena bounds utilities.
+ */
+
+import {Position} from '../types.js';
+import {ARENA_WIDTH, ARENA_HEIGHT} from '../rules.js';
+
+/**
+ * Normalize a vector to unit length.
+ * Returns {x: 0, y: 0} for zero-length vectors.
+ */
+export function normalize(vector: Position): Position
+{
+	const len = Math.sqrt(vector.x * vector.x + vector.y * vector.y);
+	if (len === 0)
+	{
+		return {x: 0, y: 0};
+	}
+	return {x: vector.x / len, y: vector.y / len};
+}
+
+/**
+ * Get normalized direction vector from one position toward another.
+ * Returns {x: 0, y: 0} if positions are identical.
+ */
+export function directionTo(from: Position, to: Position): Position
+{
+	const dx = to.x - from.x;
+	const dy = to.y - from.y;
+	return normalize({x: dx, y: dy});
+}
+
+/**
+ * Get normalized direction vector from one position away from another.
+ * Returns {x: 0, y: 0} if positions are identical.
+ */
+export function directionAway(from: Position, to: Position): Position
+{
+	const dir = directionTo(from, to);
+	return {x: -dir.x, y: -dir.y};
+}
+
+/**
+ * Clamp a position to valid arena bounds.
+ * Note: For wizard-specific clamping with radius, use clampToArena from physics.ts
+ */
+export function clampPositionToArena(position: Position): Position
+{
+	return {
+		x: Math.max(0, Math.min(ARENA_WIDTH, position.x)),
+		y: Math.max(0, Math.min(ARENA_HEIGHT, position.y)),
+	};
+}
+
+/**
+ * Get the length/magnitude of a vector.
+ */
+export function magnitude(vector: Position): number
+{
+	return Math.sqrt(vector.x * vector.x + vector.y * vector.y);
+}

package/src/utils/targeting.ts

@@ -0,0 +1,45 @@
+import {Position} from '../types.js';
+import {distanceTo} from './distance.js';
+
+/**
+ * Find the nearest entity from a list.
+ */
+export function findNearest<T extends {position: Position}>(from: Position, entities: T[]): T | null
+{
+	if (entities.length === 0)
+	{
+		return null;
+	}
+
+	let nearest = entities[0]!;
+	let minDistance = distanceTo(from, nearest.position);
+
+	for (let i = 1; i < entities.length; i++)
+	{
+		const entity = entities[i]!;
+		const distance = distanceTo(from, entity.position);
+		if (distance < minDistance)
+		{
+			minDistance = distance;
+			nearest = entity;
+		}
+	}
+
+	return nearest;
+}
+
+/**
+ * Find all entities within a certain range.
+ */
+export function findInRange<T extends {position: Position}>(from: Position, entities: T[], range: number): T[]
+{
+	return entities.filter((entity) => distanceTo(from, entity.position) <= range);
+}
+
+/**
+ * Sort entities by distance (closest first).
+ */
+export function sortByDistance<T extends {position: Position}>(from: Position, entities: T[]): T[]
+{
+	return [...entities].sort((a, b) => distanceTo(from, a.position) - distanceTo(from, b.position));
+}