@vibemancer/core 0.1.0

package/src/engine/manual-match.ts

@@ -0,0 +1,289 @@
+/**
+ * VIBEMANCER - MANUAL MATCH
+ *
+ * Tick-by-tick match runner used by manual play mode. Wraps the same
+ * `tick()` primitive that `simulate()` uses, so stepping forward
+ * produces the same trajectory as a batched `simulate()` with the
+ * same seed.
+ *
+ * Extra capabilities over `simulate()`:
+ * - step(N) advances N ticks at a time (default 1) — caller controls pacing
+ * - replaceMissileAI(id, ai) hot-swaps a missile's AI mid-flight (used by
+ *   the missile-hijack feature in manual play)
+ * - setInvincible(wizardIndex, on) toggles damage immunity per wizard
+ */
+
+import {
+	ARENA_HEIGHT,
+	ARENA_WIDTH,
+	MATCH_DURATION,
+	SPAWN_DISTANCE,
+	TICKS_PER_SECOND,
+	WIZARD_HEALTH,
+} from '../rules.js';
+import type {
+	GameConfig,
+	GameState,
+	MissileAIFunction,
+	ProjectileState,
+	WizardFunction,
+} from '../types.js';
+import {clearHooks} from './hooks-runtime.js';
+import {
+	type BotError,
+	type InternalWizardState,
+	type MatchWinner,
+	type SimulateResult,
+	getPlayerState,
+	tick,
+} from './simulation.js';
+
+export interface ManualMatchOptions
+{
+	seed?: number;
+	spawnDistance?: number;
+	maxTicks?: number;
+}
+
+export interface StepResult
+{
+	gameState: GameState;
+	errors: BotError[];
+	done: boolean;
+}
+
+/**
+ * Build the initial pair of internal wizards for a match. Mirrors the
+ * inline setup in simulate() so both code paths produce identical state.
+ */
+function createInitialWizards(spawnDistance: number): InternalWizardState[]
+{
+	return [
+		{
+			id: 'wizard-1',
+			position: {x: ARENA_WIDTH / 2 - spawnDistance / 2, y: ARENA_HEIGHT / 2},
+			rotation: 0,
+			health: WIZARD_HEALTH,
+			maxHealth: WIZARD_HEALTH,
+			state: 'idle',
+			blinkCooldown: 0,
+			velocity: {x: 0, y: 0},
+			damageDealt: 0,
+			damageTaken: 0,
+			lastHitTick: 0,
+		},
+		{
+			id: 'wizard-2',
+			position: {x: ARENA_WIDTH / 2 + spawnDistance / 2, y: ARENA_HEIGHT / 2},
+			rotation: 180,
+			health: WIZARD_HEALTH,
+			maxHealth: WIZARD_HEALTH,
+			state: 'idle',
+			blinkCooldown: 0,
+			velocity: {x: 0, y: 0},
+			damageDealt: 0,
+			damageTaken: 0,
+			lastHitTick: 0,
+		},
+	];
+}
+
+export class ManualMatch
+{
+	private readonly wizard1AI: WizardFunction;
+	private readonly wizard2AI: WizardFunction;
+	private readonly seed: number;
+	private readonly maxTicks: number;
+	private readonly config: GameConfig;
+
+	private wizards: InternalWizardState[];
+	private projectiles: ProjectileState[] = [];
+	private missileAIs: Map<string, MissileAIFunction> = new Map();
+	/** First-replacement originals for hijacked missiles. Used by restoreMissileAI. */
+	private originalMissileAIs: Map<string, MissileAIFunction> = new Map();
+	private currentTick = 0;
+	private done = false;
+	private allErrors: BotError[] = [];
+	private history: GameState[];
+
+	constructor(wizard1AI: WizardFunction, wizard2AI: WizardFunction, options: ManualMatchOptions = {})
+	{
+		if (typeof wizard1AI !== 'function')
+		{
+			throw new Error('wizard1AI must be a function');
+		}
+		if (typeof wizard2AI !== 'function')
+		{
+			throw new Error('wizard2AI must be a function');
+		}
+
+		this.wizard1AI = wizard1AI;
+		this.wizard2AI = wizard2AI;
+
+		const {
+			seed: rawSeed = Date.now(),
+			spawnDistance: rawSpawn,
+			maxTicks: rawMaxTicks = MATCH_DURATION,
+		} = options;
+
+		this.seed = Number.isFinite(rawSeed) ? Math.floor(rawSeed) & 0x7FFFFFFF : Date.now() & 0x7FFFFFFF;
+		this.maxTicks = Number.isFinite(rawMaxTicks) && rawMaxTicks > 0
+			? Math.min(Math.floor(rawMaxTicks), 100000)
+			: MATCH_DURATION;
+		const spawnDistance = Number.isFinite(rawSpawn) && rawSpawn! > 0
+			? Math.min(rawSpawn!, Math.min(ARENA_WIDTH, ARENA_HEIGHT) - 100)
+			: SPAWN_DISTANCE;
+
+		this.config = Object.freeze({
+			arenaSize: Object.freeze({width: ARENA_WIDTH, height: ARENA_HEIGHT}),
+			tickRate: TICKS_PER_SECOND,
+			maxTicks: this.maxTicks,
+		});
+
+		// Hook state must start clean — bot useState/useRef from a previous
+		// match would otherwise leak in.
+		clearHooks('wizard-1');
+		clearHooks('wizard-2');
+
+		this.wizards = createInitialWizards(spawnDistance);
+		this.history = [getPlayerState(0, this.wizards, this.projectiles, 0)];
+	}
+
+	/**
+	 * Advance the match by `count` ticks (default 1). Stops early if the
+	 * match completes mid-batch.
+	 */
+	step(count = 1): StepResult
+	{
+		const errorsThisCall: BotError[] = [];
+		for (let i = 0; i < count; i++)
+		{
+			if (this.done) break;
+			const result = tick(
+				this.currentTick,
+				this.wizard1AI,
+				this.wizard2AI,
+				this.config,
+				this.wizards,
+				this.projectiles,
+				this.missileAIs,
+				this.seed,
+			);
+			this.currentTick = result.nextTick;
+			this.wizards = result.wizards;
+			this.projectiles = result.projectiles;
+			if (result.errors.length > 0)
+			{
+				this.allErrors.push(...result.errors);
+				errorsThisCall.push(...result.errors);
+			}
+
+			this.history.push(getPlayerState(0, this.wizards, this.projectiles, this.currentTick));
+
+			if (
+				this.wizards[0]!.health <= 0
+				|| this.wizards[1]!.health <= 0
+				|| this.currentTick >= this.maxTicks
+			)
+			{
+				this.done = true;
+			}
+		}
+
+		return {
+			gameState: this.getGameState(),
+			errors: errorsThisCall,
+			done: this.done,
+		};
+	}
+
+	/**
+	 * Hot-swap a missile's AI function. Used by the missile-hijack feature
+	 * in manual play. The first replacement remembers the original AI so
+	 * `restoreMissileAI` can put it back. Subsequent replacements update
+	 * the active AI but leave the remembered original alone.
+	 *
+	 * No-op if the projectile id doesn't exist.
+	 */
+	replaceMissileAI(projectileId: string, ai: MissileAIFunction): void
+	{
+		const existing = this.missileAIs.get(projectileId);
+		if (!existing) return;
+		if (!this.originalMissileAIs.has(projectileId))
+		{
+			this.originalMissileAIs.set(projectileId, existing);
+		}
+		this.missileAIs.set(projectileId, ai);
+	}
+
+	/**
+	 * Restore a previously hijacked missile's original AI function.
+	 * No-op if the projectile id doesn't exist or was never hijacked.
+	 */
+	restoreMissileAI(projectileId: string): void
+	{
+		const original = this.originalMissileAIs.get(projectileId);
+		if (!original) return;
+		if (!this.missileAIs.has(projectileId)) return;
+		this.missileAIs.set(projectileId, original);
+		this.originalMissileAIs.delete(projectileId);
+	}
+
+	/**
+	 * Set the invincibility flag for a wizard. Invincible wizards take 0
+	 * damage from all sources.
+	 */
+	setInvincible(wizardIndex: 0 | 1, on: boolean): void
+	{
+		const wizard = this.wizards[wizardIndex];
+		if (!wizard) return;
+		wizard.invincible = on;
+	}
+
+	/**
+	 * Get the current game state from wizard-1's perspective.
+	 * Returned object is a deep clone — safe to mutate.
+	 */
+	getGameState(): GameState
+	{
+		return getPlayerState(0, this.wizards, this.projectiles, this.currentTick);
+	}
+
+	getCurrentTick(): number
+	{
+		return this.currentTick;
+	}
+
+	isComplete(): {done: boolean; winner: MatchWinner}
+	{
+		return {done: this.done, winner: this.done ? this.computeWinner() : null};
+	}
+
+	getResult(): SimulateResult
+	{
+		return {
+			winner: this.computeWinner(),
+			ticks: this.currentTick,
+			finalState: this.getGameState(),
+			history: this.history,
+			errors: this.allErrors,
+		};
+	}
+
+	dispose(): void
+	{
+		clearHooks('wizard-1');
+		clearHooks('wizard-2');
+		this.history = [];
+	}
+
+	private computeWinner(): MatchWinner
+	{
+		const w1 = this.wizards[0]!;
+		const w2 = this.wizards[1]!;
+		if (w1.health <= 0 && w2.health <= 0) return 'draw';
+		if (w2.health <= 0) return 'wizard-1';
+		if (w1.health <= 0) return 'wizard-2';
+		return null;
+	}
+}

package/src/engine/missile-templates.ts

@@ -0,0 +1,155 @@
+/**
+ * VIBEMANCER - MISSILE TEMPLATES
+ *
+ * Reusable missile config + AI factories for manual play and bot examples.
+ * Each factory clamps its inputs to rules.ts minimums and returns a pure
+ * AI function that's safe to register with the engine.
+ */
+
+import {
+	MISSILE_MIN_DAMAGE,
+	MISSILE_MIN_SPEED,
+	MISSILE_MIN_DURATION,
+} from '../rules.js';
+import type {MissileAIFunction, MissileConfig} from '../types.js';
+
+interface BaseParams
+{
+	damage: number;
+	speed: number;
+	duration: number;
+}
+
+interface TurningParams extends BaseParams
+{
+	turnRate: number;
+}
+
+export type StraightParams = BaseParams;
+
+export type HomingParams = TurningParams;
+
+export type AntiHomingParams = TurningParams;
+
+export interface SpiralParams extends BaseParams
+{
+	spiralRadius: number;
+	spiralFreq: number;
+}
+
+export interface SeekerParams extends TurningParams
+{
+	minLockDistance: number;
+}
+
+export interface MissileTemplate
+{
+	config: MissileConfig;
+	ai: MissileAIFunction;
+}
+
+function clampBase(p: BaseParams): {damage: number; speed: number; duration: number}
+{
+	return {
+		damage: Math.max(MISSILE_MIN_DAMAGE, p.damage),
+		speed: Math.max(MISSILE_MIN_SPEED, p.speed),
+		duration: Math.max(MISSILE_MIN_DURATION, Math.floor(p.duration)),
+	};
+}
+
+/**
+ * Fire-and-forget missile. No steering — flies in a straight line.
+ */
+export function straightMissile(p: StraightParams): MissileTemplate
+{
+	const base = clampBase(p);
+	const config: MissileConfig = {...base, turnRate: 0};
+	const ai: MissileAIFunction = () => ({});
+	return {config, ai};
+}
+
+/**
+ * Homing missile. Steers toward the enemy each tick.
+ */
+export function homingMissile(p: HomingParams): MissileTemplate
+{
+	const base = clampBase(p);
+	const config: MissileConfig = {...base, turnRate: p.turnRate};
+	const ai: MissileAIFunction = ({worldState}) =>
+	{
+		const enemy = worldState.enemies[0];
+		if (!enemy) return {};
+		return {turnToward: enemy.position};
+	};
+	return {config, ai};
+}
+
+/**
+ * Anti-homing missile. Steers AWAY from the enemy — useful as a feint or
+ * area-denial pattern.
+ */
+export function antiHomingMissile(p: AntiHomingParams): MissileTemplate
+{
+	const base = clampBase(p);
+	const config: MissileConfig = {...base, turnRate: p.turnRate};
+	const ai: MissileAIFunction = ({missileState, worldState}) =>
+	{
+		const enemy = worldState.enemies[0];
+		if (!enemy) return {};
+		// Reflect the enemy position through the missile to get an "away" target.
+		const target = {
+			x: missileState.position.x * 2 - enemy.position.x,
+			y: missileState.position.y * 2 - enemy.position.y,
+		};
+		return {turnToward: target};
+	};
+	return {config, ai};
+}
+
+/**
+ * Spiral missile. Continuously orbits its current heading while advancing.
+ * Uses missileState.remainingTicks as a deterministic phase counter so the
+ * AI is fully pure (no closure state).
+ */
+export function spiralMissile(p: SpiralParams): MissileTemplate
+{
+	const base = clampBase(p);
+	// turnRate must be high enough for the spiral to manifest visibly
+	const config: MissileConfig = {...base, turnRate: 12};
+	const radius = Math.max(1, p.spiralRadius);
+	const freq = p.spiralFreq;
+	const ai: MissileAIFunction = ({missileState}) =>
+	{
+		const phase = -missileState.remainingTicks * freq;
+		const target = {
+			x: missileState.position.x + Math.cos(phase) * radius,
+			y: missileState.position.y + Math.sin(phase) * radius,
+		};
+		return {turnToward: target};
+	};
+	return {config, ai};
+}
+
+/**
+ * Seeker missile. Homes toward the enemy, but only when farther away than
+ * minLockDistance — closer than that, the missile coasts straight (so it
+ * doesn't whirl around a target it's about to hit).
+ */
+export function seekerMissile(p: SeekerParams): MissileTemplate
+{
+	const base = clampBase(p);
+	const config: MissileConfig = {...base, turnRate: p.turnRate};
+	const minDist = Math.max(0, p.minLockDistance);
+	const minDistSq = minDist * minDist;
+	const ai: MissileAIFunction = ({missileState, worldState}) =>
+	{
+		const enemy = worldState.enemies[0];
+		if (!enemy) return {};
+		const dx = enemy.position.x - missileState.position.x;
+		const dy = enemy.position.y - missileState.position.y;
+		const distSq = dx * dx + dy * dy;
+		if (distSq < minDistSq) return {};
+		return {turnToward: enemy.position};
+	};
+	return {config, ai};
+}

package/src/engine/optimizer.ts

@@ -0,0 +1,220 @@
+/**
+ * VIBEMANCER - OPTIMIZER UTILITIES
+ *
+ * Core functions used by the offline parameter optimizer script.
+ * These handle combo generation, range narrowing, and fight scoring.
+ *
+ * The optimizer uses multi-pass coordinate descent:
+ * - Pass 1: Coarse search across the effective range for each param
+ * - Pass 2+: Fine search zoomed into the neighborhood of the best result
+ *
+ * Parameters can define their search window two ways:
+ * - `range`: sliding window centered on current value (value ± range)
+ * - `min`/`max`: fixed bounds (old-style)
+ *
+ * Both can be combined: range defines the search radius, min/max clamp it.
+ */
+
+import type {ParamDeclaration} from './params-runtime.js';
+import type {FightResult} from './simulation.js';
+import {WIZARD_HEALTH} from '../rules.js';
+
+/**
+ * Compute the effective min/max search window for a parameter.
+ *
+ * - If `range` is set: window is `[value - range, value + range]`, clamped by optional min/max
+ * - If only `min`/`max` are set: window is `[min, max]` directly
+ * - If neither: returns `[value, value]` (no search)
+ */
+export function getEffectiveRange(p: ParamDeclaration): {min: number; max: number}
+{
+	if (p.range != null)
+	{
+		return {
+			min: Math.max(p.value - p.range, p.min ?? -Infinity),
+			max: Math.min(p.value + p.range, p.max ?? Infinity),
+		};
+	}
+	return {
+		min: p.min ?? p.value,
+		max: p.max ?? p.value,
+	};
+}
+
+/**
+ * Generate evenly-spaced candidate values for a single parameter.
+ *
+ * Divides [min, max] into `steps` evenly-spaced values. For example,
+ * min=0, max=100, steps=5 produces [0, 25, 50, 75, 100].
+ *
+ * @param min - Lower bound of search range
+ * @param max - Upper bound of search range
+ * @param steps - Number of evenly-spaced values to generate (minimum 2)
+ * @returns Array of candidate values, sorted ascending
+ */
+export function generateCandidates(min: number, max: number, steps: number): number[]
+{
+	if (steps < 2) steps = 2;
+	const values: number[] = [];
+	for (let i = 0; i < steps; i++)
+	{
+		values.push(min + (max - min) * i / (steps - 1));
+	}
+	return values;
+}
+
+/**
+ * Generate all combinations (cartesian product) of candidate values for multiple params.
+ *
+ * For N params with S1, S2, ... SN steps each, produces S1 × S2 × ... × SN combinations.
+ * Each combination is a Record<string, number> mapping param name to value.
+ *
+ * @param params - Parameter declarations with search ranges and step counts
+ * @returns Array of all parameter combinations to evaluate
+ */
+export function generateCombos(params: ParamDeclaration[]): Record<string, number>[]
+{
+	if (params.length === 0) return [{}];
+
+	// Generate candidates per param
+	const candidateArrays = params.map((p) =>
+	{
+		const {min, max} = getEffectiveRange(p);
+		return {
+			name: p.name,
+			values: generateCandidates(min, max, p.steps),
+		};
+	});
+
+	// Cartesian product
+	let combos: Record<string, number>[] = [{}];
+	for (const {name, values} of candidateArrays)
+	{
+		const next: Record<string, number>[] = [];
+		for (const combo of combos)
+		{
+			for (const value of values)
+			{
+				next.push({...combo, [name]: value});
+			}
+		}
+		combos = next;
+	}
+
+	return combos;
+}
+
+/**
+ * Narrow parameter ranges around the best combo found in the previous pass.
+ *
+ * Centers each param on its best value and shrinks the search range to one gap width.
+ * This provides finer resolution in subsequent passes. Hard min/max constraints are preserved.
+ *
+ * @param params - Original parameter declarations
+ * @param best - Best parameter combination from the previous pass
+ * @returns New parameter declarations with narrowed ranges for the next pass
+ */
+export function narrowRange(params: ParamDeclaration[], best: Record<string, number>): ParamDeclaration[]
+{
+	return params.map((p) =>
+	{
+		const bestVal = best[p.name] ?? p.value;
+		const effectiveSubsteps = p.substeps ?? p.steps;
+
+		// substeps: 0 — freeze this param at its best value (skip in subsequent passes)
+		if (effectiveSubsteps === 0)
+		{
+			return {...p, value: bestVal, min: bestVal, max: bestVal, range: undefined, steps: 2};
+		}
+
+		const {min: effMin, max: effMax} = getEffectiveRange(p);
+		const gap = (effMax - effMin) / (p.steps - 1);
+		const narrowedSteps = effectiveSubsteps;
+
+		if (p.range != null)
+		{
+			// Range mode: center on best, shrink range to one gap
+			return {...p, value: bestVal, range: gap, steps: narrowedSteps};
+		}
+		// Fixed min/max mode: narrow bounds around best, clamped to original
+		return {
+			...p,
+			min: Math.max(p.min ?? bestVal, bestVal - gap),
+			max: Math.min(p.max ?? bestVal, bestVal + gap),
+			steps: narrowedSteps,
+		};
+	});
+}
+
+/**
+ * Score a FightResult from one bot's perspective.
+ *
+ * Returns a continuous score that provides gradient information beyond binary win/loss:
+ * - Win: 3.0 base + up to 0.5 HP bonus (higher remaining HP = better)
+ * - Draw: 1.0
+ * - Loss: 0.0 base + up to 0.5 bonus for low enemy HP (closer fights = better)
+ *
+ * For a mirrored fight set (bot as wizard-1 AND wizard-2), call this twice
+ * and sum the scores for a balanced evaluation.
+ *
+ * @param result - The fight result to score
+ * @returns Continuous score in range [0, 3.5] per match
+ */
+export function scoreFight(result: FightResult): number
+{
+	let score = 0;
+
+	for (const match of result.matches)
+	{
+		if (match.winner === 'wizard-1')
+		{
+			// Won: 3.0 base + HP bonus
+			score += 3.0 + (match.finalState.health / WIZARD_HEALTH) * 0.5;
+		}
+		else if (match.winner === 'draw' || match.winner === null)
+		{
+			score += 1.0;
+		}
+		else
+		{
+			// Lost: small bonus for low enemy HP
+			const enemyHP = match.finalState.enemies[0]?.health ?? WIZARD_HEALTH;
+			score += (1 - enemyHP / WIZARD_HEALTH) * 0.5;
+		}
+	}
+
+	return score;
+}
+
+/**
+ * Score a FightResult from wizard-2's perspective.
+ * Same scoring logic as scoreFight but with roles reversed.
+ *
+ * Use this for tournaments where both sides of a pairing need scoring.
+ */
+export function scoreFightAsWizard2(result: FightResult): number
+{
+	let score = 0;
+
+	for (const match of result.matches)
+	{
+		if (match.winner === 'wizard-2')
+		{
+			// Won: 3.0 base + HP bonus (wizard-2's remaining HP)
+			const hp = match.finalState.enemies[0]?.health ?? WIZARD_HEALTH;
+			score += 3.0 + (hp / WIZARD_HEALTH) * 0.5;
+		}
+		else if (match.winner === 'draw' || match.winner === null)
+		{
+			score += 1.0;
+		}
+		else
+		{
+			// Lost: small bonus for low wizard-1 HP
+			const enemyHP = match.finalState.health;
+			score += (1 - enemyHP / WIZARD_HEALTH) * 0.5;
+		}
+	}
+
+	return score;
+}