@vibemancer/core 0.1.0

package/src/trace.ts

@@ -0,0 +1,430 @@
+/**
+ * VIBEMANCER - FIGHT TRACE
+ *
+ * Extracts a structured event log from a SimulateResult history.
+ * Both bots' actions are tracked: state changes, missile launches with
+ * full config, hits, damage, dodge proximity, movement patterns.
+ *
+ * Used by:
+ * - vibemancer trace (CLI debug command)
+ * - scripts/fight-trace.ts (internal diagnostic)
+ * - User tests that want event-level analysis
+ */
+
+import type {GameState, ProjectileState} from './types.js';
+import type {SimulateResult, BotError} from './engine/simulation.js';
+import {distanceTo} from './utils/distance.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TraceEvent
+{
+	tick: number;
+	/** 'W1' = wizard-1, 'W2' = wizard-2 */
+	actor: 'W1' | 'W2';
+	type: TraceEventType;
+	detail: string;
+}
+
+export type TraceEventType =
+	| 'STATE'        // State transition (idle→casting, etc.)
+	| 'FIRE'         // Missile launched (includes config + range)
+	| 'HIT'          // Damage dealt to opponent
+	| 'HURT'         // Damage taken from opponent
+	| 'DODGE_START'  // Enemy missile enters 150u proximity
+	| 'DODGE_CLOSE'  // Enemy missile enters 50u proximity
+	| 'MOVE'         // Movement summary (every 100 ticks)
+	| 'ERROR'        // Bot or missile AI threw a runtime error
+	| 'WARNING';     // Common mistake detected (move/blink confusion, etc.)
+
+export interface TraceSummary
+{
+	winner: string;
+	ticks: number;
+	w1Name: string;
+	w2Name: string;
+	w1FinalHp: number;
+	w2FinalHp: number;
+	w1: TraceBotSummary;
+	w2: TraceBotSummary;
+}
+
+export interface TraceBotSummary
+{
+	missilesLaunched: number;
+	hits: number;
+	damageDealt: number;
+	damageReceived: number;
+	shields: number;
+	blinks: number;
+	dodgeEncounters: number;
+	movement: {strafe: number; approach: number; retreat: number; still: number};
+}
+
+// ─── Event Extraction ────────────────────────────────────────────────────────
+
+/**
+ * Extract a structured event log from simulation history.
+ * Tracks both bots' state changes, missile launches (with full config + range),
+ * hits, damage, dodge proximity, movement patterns, and runtime errors.
+ */
+export function extractTraceEvents(history: GameState[], errors?: BotError[]): TraceEvent[]
+{
+	const events: TraceEvent[] = [];
+
+	let prevW1State = '';
+	let prevW2State = '';
+	let prevW1Health = history[0]?.health ?? 60;
+	let prevW2Health = history[0]?.enemies[0]?.health ?? 60;
+	let prevW1Spell = '';
+	let prevW2Spell = '';
+	const prevProjectileIds = new Set<string>();
+
+	for (let i = 0; i < history.length; i++)
+	{
+		const state = history[i]!;
+		const tick = state.tick;
+		const enemy = state.enemies[0]!;
+		const distance = distanceTo(state.position, enemy.position);
+
+		// --- W1 state transitions ---
+		const w1State = state.state;
+		const w1Spell = state.castingSpell ?? state.channelingSpell ?? '';
+		if (w1State !== prevW1State || w1Spell !== prevW1Spell)
+		{
+			let detail = `${prevW1State || '?'}→${w1State}`;
+			if (w1Spell) detail += ` (${w1Spell})`;
+			if (w1State === 'casting' && state.castDuration) detail += ` [${state.castDuration}t]`;
+			detail += ` dist=${distance.toFixed(0)}`;
+			events.push({tick, actor: 'W1', type: 'STATE', detail});
+		}
+
+		// --- W2 state transitions ---
+		const w2State = enemy.state;
+		const w2Spell = enemy.castingSpell ?? enemy.channelingSpell ?? '';
+		if (w2State !== prevW2State || w2Spell !== prevW2Spell)
+		{
+			let detail = `${prevW2State || '?'}→${w2State}`;
+			if (w2Spell) detail += ` (${w2Spell})`;
+			if (w2State === 'casting' && enemy.castDuration) detail += ` [${enemy.castDuration}t]`;
+			detail += ` dist=${distance.toFixed(0)}`;
+			events.push({tick, actor: 'W2', type: 'STATE', detail});
+		}
+
+		// --- Damage events ---
+		if (enemy.health < prevW2Health)
+		{
+			const dmg = prevW2Health - enemy.health;
+			events.push({
+				tick, actor: 'W1', type: 'HIT',
+				detail: `dealt ${dmg.toFixed(1)} → enemy HP=${enemy.health.toFixed(1)} dist=${distance.toFixed(0)}`,
+			});
+		}
+		if (state.health < prevW1Health)
+		{
+			const dmg = prevW1Health - state.health;
+			const stateTag = state.state === 'channeling' ? ' (SHIELDED)'
+				: state.state === 'casting' ? ` (CASTING ${state.castingSpell})`
+					: state.state === 'gcd_locked' ? ' (GCD)'
+						: ` (${state.state})`;
+			events.push({
+				tick, actor: 'W1', type: 'HURT',
+				detail: `took ${dmg.toFixed(1)} → HP=${state.health.toFixed(1)}${stateTag} dist=${distance.toFixed(0)}`,
+			});
+		}
+		// W2 damage taken = W1 damage dealt (already covered above as HIT)
+		// W2 damage dealt = W1 damage taken (already covered above as HURT)
+
+		// --- Missile launches (with full config) ---
+		const currentIds = new Set<string>();
+		for (const proj of state.projectiles)
+		{
+			currentIds.add(proj.id);
+			if (!prevProjectileIds.has(proj.id))
+			{
+				const owner: 'W1' | 'W2' = proj.ownerId === 'wizard-1' ? 'W1' : 'W2';
+				const range = (proj.speed * proj.remainingTicks).toFixed(0);
+				events.push({
+					tick, actor: owner, type: 'FIRE',
+					detail: `dmg=${proj.damage} spd=${proj.speed} turn=${proj.turnRate} life=${proj.remainingTicks} range=${range} dist=${distance.toFixed(0)}`,
+				});
+				// Warn if missile range < distance (will expire before reaching target)
+				if (proj.speed * proj.remainingTicks < distance * 0.8 && proj.turnRate >= 0)
+				{
+					events.push({
+						tick, actor: owner, type: 'WARNING',
+						detail: `missile range (${range}) may be too short for distance (${distance.toFixed(0)}) — consider increasing duration`,
+					});
+				}
+			}
+		}
+		prevProjectileIds.clear();
+		for (const id of currentIds) prevProjectileIds.add(id);
+
+		// --- Dodge proximity events (enemy missiles approaching W1) ---
+		if (i > 0)
+		{
+			const speed = Math.sqrt(state.velocity.x ** 2 + state.velocity.y ** 2);
+			for (const proj of state.projectiles)
+			{
+				if (proj.ownerId === 'wizard-1') continue;
+				const missileDistance = distanceTo(state.position, proj.position);
+				const prevProj = history[i - 1]!.projectiles.find((p) => p.id === proj.id);
+				const prevMissileDist = prevProj ? distanceTo(history[i - 1]!.position, prevProj.position) : Infinity;
+
+				if (missileDistance <= 150 && prevMissileDist > 150)
+				{
+					events.push({
+						tick, actor: 'W1', type: 'DODGE_START',
+						detail: formatDodgeDetail(state, proj, missileDistance, speed),
+					});
+				}
+				if (missileDistance <= 50 && prevMissileDist > 50)
+				{
+					events.push({
+						tick, actor: 'W1', type: 'DODGE_CLOSE',
+						detail: formatDodgeDetail(state, proj, missileDistance, speed),
+					});
+				}
+			}
+		}
+
+		// --- Movement summary every 100 ticks ---
+		if (tick > 0 && tick % 100 === 0)
+		{
+			const speed = Math.sqrt(state.velocity.x ** 2 + state.velocity.y ** 2);
+			const moveType = classifyMovement(state, enemy, speed);
+			const incomingMissiles = state.projectiles.filter((p) => p.ownerId !== 'wizard-1').length;
+			events.push({
+				tick, actor: 'W1', type: 'MOVE',
+				detail: `${moveType} spd=${speed.toFixed(2)} dist=${distance.toFixed(0)} missiles=${incomingMissiles} ${state.state} hp=${state.health.toFixed(1)}`,
+			});
+		}
+
+		prevW1State = w1State;
+		prevW2State = w2State;
+		prevW1Health = state.health;
+		prevW2Health = enemy.health;
+		prevW1Spell = w1Spell;
+		prevW2Spell = w2Spell;
+	}
+
+	// --- Inject runtime errors as ERROR events ---
+	if (errors && errors.length > 0)
+	{
+		for (const err of errors)
+		{
+			const actor: 'W1' | 'W2' = err.entityId === 'wizard-1' ? 'W1'
+				: err.entityId === 'wizard-2' ? 'W2'
+					: err.entityId.startsWith('missile') ? (/* missile errors attributed to owner */ 'W1') : 'W1';
+			events.push({
+				tick: err.tick,
+				actor,
+				type: 'ERROR',
+				detail: err.message,
+			});
+		}
+		// Re-sort by tick so errors appear in chronological order
+		events.sort((a, b) => a.tick - b.tick || (a.type === 'ERROR' ? 1 : 0));
+	}
+
+	return events;
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a summary from trace events and the simulation result.
+ */
+export function summarizeTrace(
+	events: TraceEvent[],
+	result: SimulateResult,
+	w1Name: string,
+	w2Name: string,
+): TraceSummary
+{
+	const final = result.history[result.history.length - 1];
+
+	function botSummary(actor: 'W1' | 'W2'): TraceBotSummary
+	{
+		const myEvents = events.filter((e) => e.actor === actor);
+		const moveEvents = myEvents.filter((e) => e.type === 'MOVE');
+		return {
+			missilesLaunched: myEvents.filter((e) => e.type === 'FIRE').length,
+			hits: myEvents.filter((e) => e.type === 'HIT').length,
+			damageDealt: myEvents.filter((e) => e.type === 'HIT').reduce((sum, e) =>
+			{
+				const m = e.detail.match(/dealt ([\d.]+)/);
+				return sum + (m ? parseFloat(m[1]!) : 0);
+			}, 0),
+			damageReceived: myEvents.filter((e) => e.type === 'HURT').reduce((sum, e) =>
+			{
+				const m = e.detail.match(/took ([\d.]+)/);
+				return sum + (m ? parseFloat(m[1]!) : 0);
+			}, 0),
+			shields: myEvents.filter((e) => e.type === 'STATE' && e.detail.includes('shield')).length,
+			blinks: myEvents.filter((e) => e.type === 'STATE' && e.detail.includes('blink')).length,
+			dodgeEncounters: myEvents.filter((e) => e.type.startsWith('DODGE')).length,
+			movement: {
+				strafe: moveEvents.filter((e) => e.detail.startsWith('STRAFE')).length,
+				approach: moveEvents.filter((e) => e.detail.startsWith('APPROACH')).length,
+				retreat: moveEvents.filter((e) => e.detail.startsWith('RETREAT')).length,
+				still: moveEvents.filter((e) => e.detail.startsWith('STILL')).length,
+			},
+		};
+	}
+
+	const winnerName = result.winner === 'wizard-1' ? w1Name
+		: result.winner === 'wizard-2' ? w2Name
+			: result.winner === 'draw' ? 'draw'
+				: 'timeout';
+
+	return {
+		winner: winnerName,
+		ticks: result.ticks,
+		w1Name,
+		w2Name,
+		w1FinalHp: final?.health ?? 0,
+		w2FinalHp: final?.enemies[0]?.health ?? 0,
+		w1: botSummary('W1'),
+		w2: botSummary('W2'),
+	};
+}
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+/** Format trace events as a human-readable string. */
+export function formatTraceEvents(events: TraceEvent[]): string
+{
+	return events.map((e) =>
+	{
+		const t = String(e.tick).padStart(5);
+		const a = e.actor.padEnd(2);
+		const ty = e.type.padEnd(12);
+		return `  T${t} ${a} ${ty} ${e.detail}`;
+	}).join('\n');
+}
+
+/** Format a full trace summary as a human-readable string. */
+export function formatTraceSummary(summary: TraceSummary): string
+{
+	const {w1Name, w2Name, w1, w2} = summary;
+	const lines = [
+		`  Winner: ${summary.winner} @ T${summary.ticks}`,
+		`  Final HP: ${w1Name}=${summary.w1FinalHp.toFixed(1)}, ${w2Name}=${summary.w2FinalHp.toFixed(1)}`,
+		'',
+		`  ${w1Name}: ${w1.missilesLaunched} missiles, ${w1.hits} hits (${w1.missilesLaunched > 0 ? ((w1.hits / w1.missilesLaunched) * 100).toFixed(0) : 'N/A'}%), ${w1.damageDealt.toFixed(1)} dmg dealt, ${w1.damageReceived.toFixed(1)} dmg taken, ${w1.shields} shields, ${w1.blinks} blinks`,
+		`  ${w2Name}: ${w2.missilesLaunched} missiles, ${w2.hits} hits (${w2.missilesLaunched > 0 ? ((w2.hits / w2.missilesLaunched) * 100).toFixed(0) : 'N/A'}%), ${w2.damageDealt.toFixed(1)} dmg dealt, ${w2.damageReceived.toFixed(1)} dmg taken, ${w2.shields} shields, ${w2.blinks} blinks`,
+		'',
+		`  ${w1Name} movement: ${w1.movement.approach} approach, ${w1.movement.strafe} strafe, ${w1.movement.retreat} retreat, ${w1.movement.still} still | ${w1.dodgeEncounters} dodge encounters`,
+	];
+	return lines.join('\n');
+}
+
+/**
+ * Generate diagnostic tips based on trace analysis.
+ * Identifies common problems and suggests fixes.
+ * Returns an array of human-readable tips (empty if no issues found).
+ */
+export function diagnoseTrace(events: TraceEvent[], summary: TraceSummary): string[]
+{
+	const tips: string[] = [];
+	const {w1} = summary;
+
+	// Check for runtime errors
+	const errors = events.filter((e) => e.actor === 'W1' && e.type === 'ERROR');
+	if (errors.length > 0)
+	{
+		const firstErr = errors[0]!;
+		tips.push(`BOT ERROR: Your bot threw "${firstErr.detail}" on tick ${firstErr.tick}. The bot does nothing when it throws. Fix this first.`);
+		if (errors.length > 1) tips.push(`  (${errors.length} total errors — likely the same bug repeating every tick)`);
+	}
+
+	// Check for range warnings
+	const rangeWarnings = events.filter((e) => e.actor === 'W1' && e.type === 'WARNING' && e.detail.includes('range'));
+	if (rangeWarnings.length > 0)
+	{
+		tips.push(`RANGE: ${rangeWarnings.length} of your missiles had range shorter than target distance. Increase missile duration or get closer before firing.`);
+	}
+
+	// No missiles fired
+	if (w1.missilesLaunched === 0 && errors.length === 0)
+	{
+		tips.push('NO OFFENSE: Your bot fired 0 missiles. Check that you return missile() when useTicksUntilReady() === 0.');
+	}
+
+	// Very low hit rate
+	if (w1.missilesLaunched >= 3 && w1.hits === 0)
+	{
+		tips.push(`ACCURACY: Fired ${w1.missilesLaunched} missiles but 0 hit. Consider: more homing (higher turnRate), or use getLeadPosition() for straight missiles, or get closer.`);
+	}
+	else if (w1.missilesLaunched >= 5 && w1.hits / w1.missilesLaunched < 0.25)
+	{
+		tips.push(`LOW ACCURACY: Only ${((w1.hits / w1.missilesLaunched) * 100).toFixed(0)}% hit rate. Try increasing turnRate for more homing, or use getLeadPosition() for prediction.`);
+	}
+
+	// No shields against incoming damage
+	if (w1.damageReceived > 20 && w1.shields === 0)
+	{
+		tips.push(`NO DEFENSE: Took ${w1.damageReceived.toFixed(0)} damage with 0 shields. Use useThreats() to detect incoming missiles and shield() when you can't dodge.`);
+	}
+
+	// Too much idle time
+	if (summary.ticks > 500)
+	{
+		const idleMovements = w1.movement.still;
+		const totalMovements = idleMovements + w1.movement.approach + w1.movement.strafe + w1.movement.retreat;
+		if (totalMovements > 0 && idleMovements / totalMovements > 0.5)
+		{
+			tips.push(`IDLE: Your bot was stationary ${((idleMovements / totalMovements) * 100).toFixed(0)}% of the time. Move to dodge missiles and close distance.`);
+		}
+	}
+
+	return tips;
+}
+
+/** Format diagnostic tips as a human-readable string. */
+export function formatDiagnosis(tips: string[]): string
+{
+	if (tips.length === 0) return '';
+	const lines = ['  Diagnosis:'];
+	for (const tip of tips)
+	{
+		lines.push(`    - ${tip}`);
+	}
+	return lines.join('\n');
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function formatDodgeDetail(state: GameState, proj: ProjectileState, missileDistance: number, speed: number): string
+{
+	const angle = dodgeAngle(state.velocity, proj.rotation);
+	return `missile at ${missileDistance.toFixed(0)}u rot=${proj.rotation.toFixed(0)}° dodge_angle=${angle.toFixed(0)}° ` +
+		`spd=${speed.toFixed(2)} ${state.state}`;
+}
+
+function dodgeAngle(wizardVelocity: {x: number; y: number}, missileRotation: number): number
+{
+	const speed = Math.sqrt(wizardVelocity.x ** 2 + wizardVelocity.y ** 2);
+	if (speed < 0.01) return 0;
+	const missileRad = missileRotation * (Math.PI / 180);
+	const dot = Math.cos(missileRad) * (wizardVelocity.x / speed) + Math.sin(missileRad) * (wizardVelocity.y / speed);
+	return Math.acos(Math.max(-1, Math.min(1, Math.abs(dot)))) * (180 / Math.PI);
+}
+
+function classifyMovement(state: GameState, enemy: GameState['enemies'][0], speed: number): string
+{
+	if (speed < 0.1) return 'STILL';
+	const toEnemyAngle = Math.atan2(enemy.position.y - state.position.y, enemy.position.x - state.position.x);
+	const moveAngle = Math.atan2(state.velocity.y, state.velocity.x);
+	let angleDiff = ((moveAngle - toEnemyAngle) * 180 / Math.PI) % 360;
+	if (angleDiff > 180) angleDiff -= 360;
+	if (angleDiff < -180) angleDiff += 360;
+	const absAngle = Math.abs(angleDiff);
+	if (absAngle < 30) return 'APPROACH';
+	if (absAngle > 150) return 'RETREAT';
+	if (absAngle >= 60 && absAngle <= 120) return 'STRAFE';
+	if (absAngle < 60) return 'APPROACH+STRAFE';
+	return 'RETREAT+STRAFE';
+}

package/src/types.ts

@@ -0,0 +1,193 @@
+/**
+ * VIBEMANCER - TYPES
+ *
+ * This file contains all the TypeScript interfaces used by the game engine.
+ */
+
+/**
+ * Position in 2D space.
+ */
+export interface Position
+{
+	x: number;
+	y: number;
+}
+
+/**
+ * Velocity in 2D space (units per tick).
+ */
+export interface Velocity
+{
+	x: number;
+	y: number;
+}
+
+/**
+ * Wizard state.
+ */
+export interface WizardState
+{
+	id: string;
+	position: Position;
+	rotation: number; // degrees
+	health: number;
+	maxHealth: number;
+	state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+	castingSpell?: 'missile' | 'shield' | 'blink';
+	castProgress?: number; // ticks elapsed
+	castDuration?: number; // total ticks needed
+	channelingSpell?: 'shield';
+	channelDuration?: number; // ticks spent channeling (for decay calc)
+	gcdRemaining?: number; // ticks remaining
+	blinkCooldown: number; // ticks remaining
+	velocity: Velocity;
+	lastMissileConfig?: MissileConfig; // last fired missile (for warmup system)
+	warmupMultiplier?: number; // warmup multiplier applied to most recent missile cast (0.80 = full bonus, 1.20 = full penalty)
+	invincible?: boolean; // manual play mode: damage is ignored when true
+}
+
+/**
+ * Projectile (missile) state.
+ */
+export interface ProjectileState
+{
+	id: string;
+	type: 'missile';
+	ownerId: string;
+	position: Position;
+	rotation: number; // degrees
+	speed: number; // units per tick
+	turnRate: number; // degrees per tick
+	damage: number;
+	remainingTicks: number;
+}
+
+/**
+ * Game configuration (read-only).
+ */
+export interface GameConfig
+{
+	arenaSize: {
+		width: number;
+		height: number;
+	};
+	tickRate: number;
+	maxTicks: number;
+}
+
+/**
+ * Full game state passed to wizard.
+ */
+export interface GameState
+{
+	tick: number;
+	position: Position;
+	rotation: number;
+	health: number;
+	maxHealth: number;
+	state: WizardState['state'];
+	castingSpell?: 'missile' | 'shield' | 'blink';
+	castProgress?: number;
+	castDuration?: number;
+	channelingSpell?: 'shield';
+	channelDuration?: number;
+	gcdRemaining?: number;
+	blinkCooldown: number;
+	velocity: Velocity;
+	lastMissileConfig?: MissileConfig; // last fired missile (for warmup system)
+	warmupMultiplier?: number; // warmup multiplier applied to most recent missile cast (0.80 = full bonus, 1.20 = full penalty)
+	enemies: WizardState[];
+	projectiles: ProjectileState[]; // all projectiles (yours and enemy's)
+	myProjectiles: ProjectileState[]; // only your active projectiles
+
+	// Combat tracking (for new hooks API)
+	damageDealt: number;   // total damage dealt this match
+	damageTaken: number;   // total damage taken this match
+	lastHitTick: number;   // tick when last took damage (0 if never)
+}
+
+/**
+ * Actions returned by wizard each tick.
+ *
+ * Movement uses world-space coordinates:
+ * - x: +100 = right, -100 = left
+ * - y: +100 = down, -100 = up
+ * - Diagonal movement is normalized (magnitude capped at 100)
+ * - No rotation tracking - just output (x, y) direction
+ */
+export interface WizardActions
+{
+	/**
+	 * Movement direction in world-space.
+	 * Values are clamped to [-100, 100] range.
+	 * Magnitude is normalized to max 100 for diagonal movement.
+	 */
+	move: {
+		x: number;
+		y: number;
+	};
+
+	/**
+	 * Start a new cast (only works if state === 'idle').
+	 */
+	startCast?: {
+		spell: 'missile';
+		config: MissileConfig;
+		missileAI: MissileAIFunction;
+		direction?: number; // initial rotation override (auto-aims at enemy by default)
+	} | {
+		spell: 'shield';
+	} | {
+		spell: 'blink';
+		target: Position; // clamped to max range
+	};
+
+	/**
+	 * Cancel current cast or channel (works if casting or channeling).
+	 */
+	cancel?: boolean;
+
+	/**
+	 * Update aim direction while casting a missile (degrees).
+	 * The missile fires in this direction at launch, allowing tracking during cast.
+	 * Only applies while state === 'casting' and castingSpell === 'missile'.
+	 */
+	aimDirection?: number;
+}
+
+/**
+ * Missile configuration.
+ */
+export interface MissileConfig
+{
+	damage: number;
+	speed: number; // units per tick
+	turnRate: number; // degrees per tick
+	duration: number; // ticks (determines range and cast time)
+}
+
+/**
+ * Missile AI function type.
+ */
+export type MissileAIFunction = (props: {
+	missileState: ProjectileState;
+	worldState: GameState;
+	random: () => number; // Seeded PRNG, isolated per entity, 0-1 range
+}) => MissileActions;
+
+/**
+ * Actions returned by missile each tick.
+ */
+export interface MissileActions
+{
+	turnToward?: Position; // engine handles turn rate limit
+}
+
+/**
+ * Main wizard function type.
+ */
+export type WizardFunction = (props: {
+	state: GameState;
+	config: GameConfig;
+	random: () => number; // Seeded PRNG, isolated per entity, 0-1 range
+}) => WizardActions;

package/src/utils/angles.ts

@@ -0,0 +1,47 @@
+import {Position} from '../types.js';
+
+/**
+ * Calculate the angle from one point to another in degrees.
+ * 0° = right, 90° = down, 180° = left, 270° = up.
+ */
+export function angleTo(from: Position, to: Position): number
+{
+	const dx = to.x - from.x;
+	const dy = to.y - from.y;
+	const radians = Math.atan2(dy, dx);
+	return normalizeAngle(radians * (180 / Math.PI));
+}
+
+/**
+ * Normalize an angle to the 0-360 range.
+ */
+export function normalizeAngle(angle: number): number
+{
+	let normalized = angle % 360;
+	if (normalized < 0)
+	{
+		normalized += 360;
+	}
+	return normalized;
+}
+
+/**
+ * Calculate the shortest difference between two angles (-180 to +180).
+ */
+export function angleDiff(angleA: number, angleB: number): number
+{
+	let diff = (angleB - angleA + 180) % 360 - 180;
+	if (diff < -180)
+	{
+		diff += 360;
+	}
+	return diff;
+}
+
+/**
+ * Check if an angle is within a certain range of a target angle.
+ */
+export function angleInRange(angle: number, target: number, range: number): boolean
+{
+	return Math.abs(angleDiff(angle, target)) <= range;
+}