@vibemancer/core 0.1.0

package/src/engine/params-runtime.ts

@@ -0,0 +1,189 @@
+/**
+ * VIBEMANCER - PARAMETER RUNTIME
+ *
+ * Provides the useParam() hook for bots to declare tunable parameters,
+ * and the infrastructure for the optimizer to inject/discover parameter values.
+ *
+ * Design: Module-level state (JS is single-threaded, no race conditions).
+ * The optimizer sets param values before running a bot, and clears them after.
+ * During discovery, all useParam calls are recorded.
+ *
+ * ## useParam API
+ *
+ * ```typescript
+ * // Basic: just a value, no optimizer config
+ * const damage = useParam('damage', 15);
+ *
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
+ *
+ * // With fixed min/max: optimizer searches [min, max] (fixed bounds)
+ * const damage = useParam('damage', 15, {min: 5, max: 25});
+ *
+ * // With all: range defines search radius, min/max clamp it
+ * const fraction = useParam('fraction', 0.25, {range: 0.2, min: 0, max: 1});
+ *
+ * // With custom step count: optimizer tests 20 values instead of default 10
+ * const distance = useParam('distance', 500, {range: 200, min: 0, steps: 20});
+ * ```
+ *
+ * - **Arg 1** `name` — unique parameter name (must be consistent across ticks)
+ * - **Arg 2** `value` — the actual value used in gameplay. This is what your bot
+ *   uses during matches. The optimizer script automatically updates this value.
+ * - **Arg 3** `config` (optional) — optimizer search configuration:
+ *   - `range` — search radius: optimizer checks `value ± range`. The auto-optimizer
+ *     rewrites `value` after each run, so the search window slides automatically.
+ *   - `min` / `max` — hard constraints (e.g., distance ≥ 0, fraction ≤ 1).
+ *     When `range` is omitted, these define fixed search bounds (old-style).
+ *   - `steps` — how many evenly-spaced values the optimizer tests per pass (default: 10).
+ *   - `substeps` — steps to use in refinement passes (passes 2+). Set to 0 to freeze
+ *     after pass 1 (ideal for boolean params). Defaults to `steps` if not specified.
+ *   - At least `range` or both `min` + `max` must be provided.
+ *
+ * Without optimizer config, useParam simply returns `value` every tick.
+ * With optimizer config, the offline optimizer script can override the value during search.
+ *
+ * ## Rules of Hooks
+ * useParam follows the same rules as useState/useEffect/etc:
+ * - Must be called at the top level of your bot function (not inside conditionals)
+ * - Must be called in the same order every tick
+ * - Violations are detected and throw errors
+ */
+
+import type {WizardFunction} from '../types.js';
+import {validateHookCall} from './hooks-runtime.js';
+
+/**
+ * Declaration of a tunable parameter, as discovered by the optimizer.
+ */
+export interface ParamDeclaration
+{
+	name: string;
+	value: number;
+	range?: number;
+	min?: number;
+	max?: number;
+	steps: number;
+	/** Steps to use in refinement passes (passes 2+). 0 = freeze after pass 1. Defaults to `steps`. */
+	substeps?: number;
+}
+
+// --- Module-level state ---
+
+/** Current parameter values injected by the optimizer. null = use defaults. */
+let paramValues: Map<string, number> | null = null;
+
+/** Params discovered during discovery mode. */
+const discoveredParams = new Map<string, ParamDeclaration>();
+
+/** Whether we're in discovery mode (collecting param declarations). */
+let discovering = false;
+
+// --- Public API for bot authors ---
+
+/**
+ * Declare a tunable parameter. Returns the current value (optimizer-injected or the provided value).
+ *
+ * @param name - Unique parameter name (consistent across ticks)
+ * @param value - The gameplay value. The auto-optimizer rewrites this in source code.
+ * @param config - Optional optimizer search configuration
+ * @returns The optimizer-injected value during optimization, or `value` during normal play
+ *
+ * @example
+ * // Simple: no optimizer config
+ * const damage = useParam('damage', 15);
+ *
+ * // With range: optimizer searches value ± range (sliding window)
+ * const distance = useParam('distance', 350, {range: 150, min: 0});
+ *
+ * // With fixed min/max: optimizer searches [min, max]
+ * const damage = useParam('damage', 15, {min: 5, max: 25});
+ */
+export function useParam(name: string, value: number, config?: {
+	range?: number;
+	min?: number;
+	max?: number;
+	steps?: number;
+	substeps?: number;
+}): number
+{
+	// Participate in hook index validation (same rules as useState, useEffect, etc.)
+	validateHookCall('useParam');
+
+	// Register for discovery (only if optimizer config is provided)
+	if (discovering && config)
+	{
+		discoveredParams.set(name, {
+			name,
+			value,
+			range: config.range,
+			min: config.min,
+			max: config.max,
+			steps: config.steps ?? 10,
+			substeps: config.substeps,
+		});
+	}
+
+	// Return optimizer value or the provided value
+	return paramValues?.get(name) ?? value;
+}
+
+// --- Optimizer API ---
+
+/**
+ * Inject parameter values for the next bot execution.
+ * The wrapped bot will read these values via useParam().
+ */
+export function setParamValues(values: Record<string, number>): void
+{
+	paramValues = new Map(Object.entries(values));
+}
+
+/**
+ * Clear injected parameter values. useParam() will return its provided value.
+ */
+export function clearParamValues(): void
+{
+	paramValues = null;
+}
+
+/**
+ * Start discovery mode. All subsequent useParam() calls with optimizer config
+ * will register their declarations.
+ */
+export function startDiscovery(): void
+{
+	discovering = true;
+	discoveredParams.clear();
+}
+
+/**
+ * Stop discovery mode and return all discovered parameter declarations.
+ */
+export function stopDiscovery(): ParamDeclaration[]
+{
+	discovering = false;
+	const result = [...discoveredParams.values()];
+	discoveredParams.clear();
+	return result;
+}
+
+/**
+ * Wrap a bot function to inject specific parameter values.
+ * The returned function sets params before calling the bot and clears them after.
+ */
+export function wrapWithParams(bot: WizardFunction, params: Record<string, number>): WizardFunction
+{
+	return (props) =>
+	{
+		setParamValues(params);
+		try
+		{
+			return bot(props);
+		}
+		finally
+		{
+			clearParamValues();
+		}
+	};
+}

package/src/engine/physics.ts

@@ -0,0 +1,143 @@
+import {Position, WizardState, ProjectileState} from '../types.js';
+import {ARENA_WIDTH, ARENA_HEIGHT, MOVEMENT_SPEED, CASTING_MOVEMENT_MULT, WIZARD_RADIUS} from '../rules.js';
+
+/**
+ * Move a wizard based on world-space input direction.
+ *
+ * Movement model (from design doc):
+ * - x: +100 = right, -100 = left
+ * - y: +100 = down, -100 = up
+ * - Values are clamped to [-100, 100]
+ * - Diagonal movement is normalized (magnitude capped at 100)
+ * - No rotation tracking - just output (x, y) direction
+ */
+export function moveWizard(wizard: WizardState, move: {x: number; y: number}, deltaTicks: number): Position
+{
+	// Clamp input values to [-100, 100]
+	let dx = Math.max(-100, Math.min(100, move.x || 0));
+	let dy = Math.max(-100, Math.min(100, move.y || 0));
+
+	// Normalize diagonal movement (cap magnitude at 100)
+	const magnitude = Math.sqrt(dx * dx + dy * dy);
+	if (magnitude > 100)
+	{
+		dx = dx * 100 / magnitude;
+		dy = dy * 100 / magnitude;
+	}
+
+	// Convert from [-100, 100] to [-1, 1] direction
+	dx = dx / 100;
+	dy = dy / 100;
+
+	let speed = MOVEMENT_SPEED;
+	if (wizard.state === 'casting')
+	{
+		speed *= CASTING_MOVEMENT_MULT;
+	}
+	else if (wizard.state === 'channeling')
+	{
+		// Movement keys ignored during channeling (design doc line 197, 1120)
+		speed = 0;
+	}
+
+	const newPos = {
+		x: wizard.position.x + dx * speed * deltaTicks,
+		y: wizard.position.y + dy * speed * deltaTicks,
+	};
+
+	return clampToArena(newPos, WIZARD_RADIUS);
+}
+
+/**
+ * Move a projectile in its current rotation direction.
+ */
+export function moveProjectile(projectile: ProjectileState, deltaTicks: number): Position
+{
+	const radians = projectile.rotation * (Math.PI / 180);
+	return {
+		x: projectile.position.x + Math.cos(radians) * projectile.speed * deltaTicks,
+		y: projectile.position.y + Math.sin(radians) * projectile.speed * deltaTicks,
+	};
+}
+
+/**
+ * Clamp a position to the arena boundaries.
+ */
+export function clampToArena(position: Position, radius: number): Position
+{
+	return {
+		x: Math.max(radius, Math.min(ARENA_WIDTH - radius, position.x)),
+		y: Math.max(radius, Math.min(ARENA_HEIGHT - radius, position.y)),
+	};
+}
+
+/**
+ * Resolve body collision between two wizards.
+ * Pushes both apart equally so they don't overlap. Neither is blocked — they just can't stack.
+ * Iterates until stable: wizard push → wall clamp → re-check overlap → repeat.
+ */
+export function resolveWizardCollision(wizard1: WizardState, wizard2: WizardState): void
+{
+	const minDist = WIZARD_RADIUS * 2;
+	const maxIterations = 5; // Prevents infinite loops in edge cases
+
+	for (let i = 0; i < maxIterations; i++)
+	{
+		const dx = wizard2.position.x - wizard1.position.x;
+		const dy = wizard2.position.y - wizard1.position.y;
+		const dist = Math.sqrt(dx * dx + dy * dy);
+
+		if (dist >= minDist) return; // No overlap — done
+
+		if (dist === 0)
+		{
+			// Exactly overlapping — push apart along arbitrary axis
+			wizard1.position = {x: wizard1.position.x - WIZARD_RADIUS, y: wizard1.position.y};
+			wizard2.position = {x: wizard2.position.x + WIZARD_RADIUS, y: wizard2.position.y};
+		}
+		else
+		{
+			const overlap = minDist - dist;
+			const pushX = (dx / dist) * (overlap / 2);
+			const pushY = (dy / dist) * (overlap / 2);
+
+			wizard1.position = {x: wizard1.position.x - pushX, y: wizard1.position.y - pushY};
+			wizard2.position = {x: wizard2.position.x + pushX, y: wizard2.position.y + pushY};
+		}
+
+		// Clamp both to arena — this may re-introduce overlap if one is pushed into a wall
+		wizard1.position = clampToArena(wizard1.position, WIZARD_RADIUS);
+		wizard2.position = clampToArena(wizard2.position, WIZARD_RADIUS);
+	}
+}
+
+/**
+ * Perform swept circle collision detection between a moving point (projectile) and a stationary circle (wizard).
+ * Returns true if a collision occurred during the movement from oldPos to newPos.
+ */
+export function sweptCircleCollision(oldPos: Position, newPos: Position, radius: number, targetPos: Position, targetRadius: number): boolean
+{
+	// Distance from point to line segment
+	const totalRadius = radius + targetRadius;
+
+	// Vector from oldPos to newPos
+	const dx = newPos.x - oldPos.x;
+	const dy = newPos.y - oldPos.y;
+	const d2 = dx * dx + dy * dy;
+
+	if (d2 === 0)
+	{
+		const dist2 = (oldPos.x - targetPos.x) ** 2 + (oldPos.y - targetPos.y) ** 2;
+		return dist2 <= totalRadius * totalRadius;
+	}
+
+	// Projection of targetPos onto the line segment (oldPos, newPos)
+	let t = ((targetPos.x - oldPos.x) * dx + (targetPos.y - oldPos.y) * dy) / d2;
+	t = Math.max(0, Math.min(1, t));
+
+	const closestX = oldPos.x + t * dx;
+	const closestY = oldPos.y + t * dy;
+
+	const dist2 = (targetPos.x - closestX) ** 2 + (targetPos.y - closestY) ** 2;
+	return dist2 <= totalRadius * totalRadius;
+}