@vibemancer/core 0.1.0

package/src/hooks/types.ts

@@ -0,0 +1,142 @@
+/**
+ * VIBEMANCER - HOOKS API TYPES
+ *
+ * Types for the hooks-based bot API.
+ *
+ * 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.
+ *   Angles:     degrees (0°=right, 90°=down, 180°=left, 270°=up)
+ */
+
+import {Position, Velocity, ProjectileState, MissileConfig, MissileAIFunction, WizardActions} from '../types.js';
+
+/**
+ * Enemy wizard state as seen by your bot.
+ *
+ * Note: you cannot see the enemy's missile configs, cooldown timers, or
+ * damage history — only what's visible on the battlefield.
+ */
+export interface EnemyState
+{
+	/** Enemy position in world coordinates (0-800). */
+	position: Position;
+	/** Enemy velocity in units/tick. */
+	velocity: Velocity;
+	/** Enemy current HP (0-60). */
+	health: number;
+	/** Enemy status: 'idle', 'casting', 'channeling' (shield), or 'gcd_locked'. */
+	status: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+	/** Which spell enemy is casting, or null. */
+	castingSpell: 'missile' | 'shield' | 'blink' | null;
+	/** Enemy shield block multiplier (0 if not shielding, 0.3-0.9 if shielding). */
+	shieldStrength: number;
+}
+
+/**
+ * Pre-computed analysis of an incoming enemy projectile.
+ *
+ * All timing values are in ticks (100 ticks = 1 second).
+ * Dodge directions are relative to missile heading, not world axes.
+ */
+export interface AnalyzedThreat
+{
+	/** Unique projectile ID. */
+	id: string;
+	/** Raw projectile state (position, rotation in degrees, speed in u/t, turnRate, remainingTicks). */
+	projectile: ProjectileState;
+
+	/** Ticks until missile hits your current position. Infinity if predicted to miss. */
+	ticksToImpact: number;
+	/** Whether the missile will hit if you stand still. */
+	willHit: boolean;
+
+	/** Whether strafing left (perpendicular to missile heading) avoids it. */
+	canDodgeLeft: boolean;
+	/** Whether strafing right (perpendicular to missile heading) avoids it. */
+	canDodgeRight: boolean;
+	/** Whether moving directly away from the missile avoids it. */
+	canOutrun: boolean;
+	/** Optimal dodge direction as a unit vector {x, y}, or null if undodgeable. */
+	bestDodgeDirection: Position | null;
+
+	/** Whether you can channel shield before the missile arrives. */
+	canBlockInTime: boolean;
+	/** Ticks from now when you should START channeling shield to block in time. */
+	ticksToStartShield: number;
+}
+
+/**
+ * Final action that can be returned from a bot.
+ * Cannot be further chained.
+ */
+export interface FinalAction
+{
+	/** Internal: extract the WizardActions */
+	readonly _toAction: () => WizardActions;
+}
+
+/**
+ * Action builder that allows chaining .move() for simultaneous movement.
+ * Returned by shield(), missile(), and cancel().
+ */
+export interface ActionBuilder extends FinalAction
+{
+	/**
+	 * Add movement to this action (e.g., move while casting).
+	 * Direction vector, not absolute position. Auto-normalized.
+	 * Positive X = right, positive Y = down.
+	 */
+	move(x: number, y: number): FinalAction;
+}
+
+/**
+ * Bot function type for the hooks API.
+ * Called every tick. Read state with hooks, return an action.
+ */
+export type BotFunction = () => FinalAction;
+
+/**
+ * Internal context for game state hooks.
+ */
+export interface BotContext
+{
+	entityId: string;
+	tick: number;
+	position: Position;
+	velocity: Velocity;
+	health: number;
+	maxHealth: number;
+	state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+	castingSpell?: 'missile' | 'shield' | 'blink';
+	castProgress?: number;
+	castDuration?: number;
+	channelingSpell?: 'shield';
+	channelDuration?: number;
+	gcdRemaining?: number;
+	blinkCooldown: number;
+	enemies: Array<{
+		id: string;
+		position: Position;
+		velocity: Velocity;
+		health: number;
+		state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+		castingSpell?: 'missile' | 'shield' | 'blink';
+		channelingSpell?: 'shield';
+		channelDuration?: number;
+	}>;
+	projectiles: ProjectileState[];
+	myProjectiles: ProjectileState[];
+	arenaWidth: number;
+	arenaHeight: number;
+	damageDealt: number;
+	damageTaken: number;
+	lastHitTick: number;
+}
+
+/**
+ * Missile configuration for action builders.
+ */
+export type {MissileConfig, MissileAIFunction};

package/src/index-browser.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser-safe entry point for @vibemancer/core.
+ *
+ * Same as index.ts but excludes sandbox.ts (which imports isolated-vm,
+ * a native Node.js addon that can't be bundled for the browser).
+ *
+ * The browser sandbox (Web Worker-based) is still exported here.
+ */
+export * from './types.js';
+export * from './rules.js';
+export * from './engine-version.js';
+export * from './engine/simulation.js';
+export * from './engine/hooks-runtime.js';
+export * from './engine/physics.js';
+export * from './engine/spells.js';
+export * from './engine/manual-match.js';
+export * from './engine/missile-templates.js';
+export * from './utils/index.js';
+export * from './bots/index.js';
+export * from './hooks/index.js';
+export * from './engine/params-runtime.js';
+export * from './engine/optimizer.js';
+export {BrowserMatchSandbox, BrowserManualMatchSandbox, browserSandboxFight, browserSandboxSimulate, createWorkerScript} from './engine/sandbox-browser.js';
+export type {BrowserSandboxOptions, ManualMatchInitOptions, ManualMatchStepRequest, WorkerFactory, WorkerLike} from './engine/sandbox-browser.js';
+export {testBot} from './testing.js';
+export {extractStats, formatStats} from './stats.js';
+export type {FightStats} from './stats.js';
+export {extractTraceEvents, summarizeTrace, formatTraceEvents, formatTraceSummary, diagnoseTrace, formatDiagnosis} from './trace.js';
+export type {TraceEvent, TraceEventType, TraceSummary, TraceBotSummary} from './trace.js';
+export type {TestBotBuilder, TestFightResult, TestSimulateResult} from './testing.js';

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from './types.js';
+export * from './rules.js';
+export * from './engine-version.js';
+export * from './engine/simulation.js';
+export * from './engine/hooks-runtime.js';
+export * from './engine/physics.js';
+export * from './engine/spells.js';
+export * from './engine/manual-match.js';
+export * from './engine/missile-templates.js';
+export * from './utils/index.js';
+export * from './bots/index.js';
+export * from './hooks/index.js';
+export * from './engine/params-runtime.js';
+export * from './engine/optimizer.js';
+export {BotBundle, compileMatchBundle, MatchSandbox, sandboxFight, sandboxSimulate} from './engine/sandbox.js';
+export type {CompileOptions, SandboxOptions} from './engine/sandbox.js';
+export {BrowserMatchSandbox, BrowserManualMatchSandbox, browserSandboxFight, browserSandboxSimulate, createWorkerScript} from './engine/sandbox-browser.js';
+export type {BrowserSandboxOptions, ManualMatchInitOptions, ManualMatchStepRequest, WorkerFactory, WorkerLike} from './engine/sandbox-browser.js';
+export {testBot} from './testing.js';
+export {extractStats, formatStats} from './stats.js';
+export type {FightStats} from './stats.js';
+export {extractTraceEvents, summarizeTrace, formatTraceEvents, formatTraceSummary, diagnoseTrace, formatDiagnosis} from './trace.js';
+export type {TraceEvent, TraceEventType, TraceSummary, TraceBotSummary} from './trace.js';
+export type {TestBotBuilder, TestFightResult, TestSimulateResult} from './testing.js';

package/src/rules.ts

@@ -0,0 +1,254 @@
+/**
+ * VIBEMANCER - GAME RULES
+ *
+ * This is the single source of truth for all game constants.
+ * All game logic imports from here. Read this to understand the game.
+ */
+
+import {MissileConfig} from './types.js';
+
+// === TIMING ===
+export const TICKS_PER_SECOND = 100;
+export const TICK_DURATION_MS = 10;
+
+// === WIZARD ===
+export const WIZARD_HEALTH = 60;
+export const WIZARD_RADIUS = 5; // units
+export const MOVEMENT_SPEED = 1; // units per tick (100 units/sec)
+export const CASTING_MOVEMENT_MULT = 0.5; // 50% speed while casting
+
+// === GCD ===
+export const GCD_DURATION = 100; // ticks (1 second)
+
+// === SHIELD ===
+export const SHIELD_CAST_TIME = 20; // ticks (0.2s)
+export const SHIELD_MAX_BLOCK = 0.9; // 90%
+export const SHIELD_DECAY_PER_SECOND = 0.2; // loses 20% per second
+export const SHIELD_MIN_BLOCK = 0.3; // 30% minimum
+// Note: Shield block % is applied directly to damage (no additional scaling)
+
+// === BLINK ===
+export const BLINK_CAST_TIME = 10; // ticks (0.1s)
+export const BLINK_RANGE = 300; // units
+export const BLINK_MAX_COOLDOWN = 2000; // ticks (20 seconds) — full-range blink
+export const BLINK_MIN_COOLDOWN = 100; // ticks (1 second) — micro-blink floor
+/** @deprecated Use BLINK_MAX_COOLDOWN */
+export const BLINK_COOLDOWN = BLINK_MAX_COOLDOWN;
+
+// === ARENA ===
+export const ARENA_WIDTH = 800;
+export const ARENA_HEIGHT = 800;
+export const ARENA_SIZE = ARENA_WIDTH; // Arena is square; alias for bot convenience
+export const SPAWN_DISTANCE = 600;
+
+// === MISSILE CONSTRAINTS ===
+export const MISSILE_MIN_DAMAGE = 1;
+export const MISSILE_MIN_SPEED = 1.5; // must be faster than player
+export const MISSILE_MIN_DURATION = 10; // ticks (0.1 seconds)
+export const MISSILE_MIN_CAST_TIME = 0.1; // seconds
+
+// === MISSILE HITBOX ===
+// Missile hitbox scales with damage (design doc line 1122)
+// Visual size reference (design doc lines 349-354):
+// - 1-5 damage: Tiny
+// - 6-15 damage: Small-Medium
+// - 16-30 damage: Large
+// - 31+ damage: Huge
+export const MISSILE_BASE_RADIUS = 2; // base radius in units
+export const MISSILE_DAMAGE_RADIUS_SCALE = 0.1; // additional radius per damage point
+
+/**
+ * Calculate missile hitbox radius based on damage.
+ */
+export function calculateMissileRadius(damage: number): number
+{
+	return MISSILE_BASE_RADIUS + damage * MISSILE_DAMAGE_RADIUS_SCALE;
+}
+
+// === MISSILE CAST TIME FORMULA ===
+// cast_time = BASE + SCALE × damage^POWER + delivery costs
+//
+// Power-law scaling: DPS always increases with damage (higher damage = more
+// DPS but longer casts that are easier to shield/dodge). Fast casts (low
+// damage) can't be shielded — that's their advantage over raw DPS.
+//
+// Reference points (stab, no delivery cost):
+//   d=10: ~1.15s cast → DPS 4.65, TTK 11.9s (fast, unshieldable)
+//   d=20: ~1.77s cast → DPS 7.23, TTK 7.3s (medium, borderline shieldable)
+//   d=30: ~2.28s cast → DPS 9.14, TTK 5.6s (slow, shieldable)
+//   d=60: ~3.57s cast → DPS 13.1, TTK 3.6s (very slow, easily shielded)
+export const MISSILE_BASE_CAST = 0.1;
+export const MISSILE_DAMAGE_SCALE = 0.226;
+export const MISSILE_DAMAGE_POWER = 2 / 3; // sublinear: DPS always increases with damage
+export const MISSILE_HOMING_COEFF = 0.12;
+export const MISSILE_TURN_DURATION_COEFF = 0.10;
+export const MISSILE_SPEED_DURATION_BASELINE = 1.5;
+export const MISSILE_SPEED_DURATION_COEFF = 0.025;
+
+/**
+ * Maps turnRate to effective cost for the cast time formula.
+ * - Positive: linear (unchanged behavior)
+ * - Negative: diminishing returns via -|t|/(1+|t|), saturating at -1.
+ *   turnRate -0.5 → -0.33, -1 → -0.5, -5 → -0.83, -10 → -0.91
+ *   Big cast speed gains from 0 to -1, worthwhile to -5, negligible after.
+ *   No hard floor — the curve naturally caps the benefit.
+ */
+export function effectiveTurnRateCost(turnRate: number): number
+{
+	if (turnRate >= 0) return turnRate;
+	const abs = Math.abs(turnRate);
+	return -(abs / (1 + abs));
+}
+
+/**
+ * Validate and sanitize missile config.
+ * Ensures all values meet minimum requirements (Lesson #9).
+ */
+export function validateMissileConfig(config: MissileConfig): MissileConfig
+{
+	return {
+		damage: Math.max(MISSILE_MIN_DAMAGE, Number.isFinite(config.damage) ? config.damage : MISSILE_MIN_DAMAGE),
+		speed: Math.max(MISSILE_MIN_SPEED, Number.isFinite(config.speed) ? config.speed : MISSILE_MIN_SPEED),
+		turnRate: Number.isFinite(config.turnRate) ? config.turnRate : 0, // no floor — diminishing returns via effectiveTurnRateCost
+		duration: Math.max(MISSILE_MIN_DURATION, Number.isFinite(config.duration) ? Math.floor(config.duration) : MISSILE_MIN_DURATION),
+	};
+}
+
+/**
+ * Calculate missile cast time from config.
+ *
+ * Base formula:
+ * cast_time = 0.1
+ *           + 0.226 × damage^(2/3)
+ *           + 0.12 × effectiveTurnRateCost(turnRate)
+ *           + 0.10 × (effectiveTurnRateCost(turnRate) × durationSeconds)
+ *           + 0.025 × (speed × durationSeconds - 1.5)
+ *
+ * effectiveTurnRateCost: linear for positive, -ln(1+|t|) for negative (diminishing returns).
+ *
+ * If lastMissileConfig is a MissileConfig, applies warmup multiplier:
+ * - Similar to previous: up to 20% faster
+ * - Very different: up to 20% slower (switching penalty)
+ */
+export function calculateMissileCastTime(config: MissileConfig, lastMissileConfig: MissileConfig | undefined | null = null): number
+{
+	const {damage, speed, turnRate, duration} = config;
+	const durationSeconds = duration / TICKS_PER_SECOND;
+	const turnCost = effectiveTurnRateCost(turnRate);
+
+	const raw = MISSILE_BASE_CAST
+		+ MISSILE_DAMAGE_SCALE * Math.pow(damage, MISSILE_DAMAGE_POWER)
+		+ MISSILE_HOMING_COEFF * turnCost
+		+ MISSILE_TURN_DURATION_COEFF * (turnCost * durationSeconds)
+		+ MISSILE_SPEED_DURATION_COEFF * (speed * durationSeconds - MISSILE_SPEED_DURATION_BASELINE);
+
+	const baseCast = Math.max(MISSILE_MIN_CAST_TIME, raw);
+
+	// Warmup is applied when lastMissileConfig is an actual MissileConfig.
+	// Note: passing undefined triggers the default (null) due to JS semantics,
+	// so in practice only an explicit MissileConfig activates warmup.
+	// - null/undefined/omitted: return base cast time (no warmup)
+	// - MissileConfig: apply warmup multiplier based on similarity to previous
+	if (lastMissileConfig !== null)
+	{
+		const multiplier = calculateWarmupMultiplier(lastMissileConfig, config);
+		return Math.max(MISSILE_MIN_CAST_TIME, baseCast * multiplier);
+	}
+
+	return baseCast;
+}
+
+// === CAST WARMUP ===
+// Repeated similar missile casts get faster ("muscle memory"), while
+// switching to a very different config incurs a penalty (slower cast).
+// This rewards specialization: melee bots that always stab have faster
+// casts than ranged bots that switch to stabs opportunistically.
+//
+// The warmup multiplier ranges from (1 - MAX_BONUS) to (1 + MAX_PENALTY):
+//   Similar to previous: cast × 0.80 (20% faster)
+//   First cast (no previous): cast × 0.80 (full warmup, no conflict)
+//   Very different from previous: cast × 1.20 (20% slower, switching penalty)
+export const WARMUP_MAX_BONUS = 0.20; // 20% cast time reduction at full warmup
+export const WARMUP_MAX_PENALTY = 0.20; // 20% cast time increase when switching
+// Tolerances for similarity calculation (differences within tolerance are "similar"):
+// Note: damage is intentionally excluded — it doesn't define playstyle.
+// A melee bot stabbing at d=10 and d=25 is the same style, just different power.
+export const WARMUP_SPEED_TOLERANCE = 3; // speed can vary ±3
+export const WARMUP_TURN_TOLERANCE = 1; // turnRate can vary ±1
+export const WARMUP_DURATION_TOLERANCE = 50; // duration (ticks) can vary ±50
+
+/**
+ * Calculate how similar two missile configs are (0 to 1).
+ * Returns 1 for identical configs, 0 for very different ones.
+ * Used by the warmup system to determine cast time multiplier.
+ *
+ * Only compares speed, turnRate, and duration — these define the missile
+ * "style" (melee stab vs ranged homing vs fast snipe). Damage is excluded
+ * because varying power doesn't change playstyle.
+ */
+export function calculateMissileSimilarity(prev: MissileConfig | undefined, current: MissileConfig): number
+{
+	if (!prev) return 1; // No previous missile = no conflicting muscle memory = full warmup
+
+	const dist = Math.abs(prev.speed - current.speed) / WARMUP_SPEED_TOLERANCE
+		+ Math.abs(prev.turnRate - current.turnRate) / WARMUP_TURN_TOLERANCE
+		+ Math.abs(prev.duration - current.duration) / WARMUP_DURATION_TOLERANCE;
+
+	return Math.max(0, 1 - dist / 3);
+}
+
+/**
+ * Calculate the cast time multiplier from the warmup system.
+ * Returns < 1 for bonus (faster), > 1 for penalty (slower), 1 for neutral.
+ *
+ * Similar to previous cast → multiplier approaches (1 - MAX_BONUS) = 0.80
+ * Very different from previous → multiplier approaches (1 + MAX_PENALTY) = 1.20
+ * No previous cast → full bonus (1 - MAX_BONUS) = 0.80
+ */
+export function calculateWarmupMultiplier(prev: MissileConfig | undefined, current: MissileConfig): number
+{
+	const similarity = calculateMissileSimilarity(prev, current);
+	// similarity=1 → bonus (faster): 1 - MAX_BONUS
+	// similarity=0 → penalty (slower): 1 + MAX_PENALTY
+	// Linear interpolation between penalty and bonus
+	return (1 + WARMUP_MAX_PENALTY) - similarity * (WARMUP_MAX_BONUS + WARMUP_MAX_PENALTY);
+}
+
+// === MATCH ===
+export const MATCH_DURATION = 30000; // ticks (5 minutes)
+
+// ============================================================
+// NEW API CONSTANT ALIASES
+// These are the preferred names for the new hooks-based API
+// ============================================================
+
+// Health & Combat
+export const MAX_HEALTH = WIZARD_HEALTH;
+export const COLLISION_RADIUS = WIZARD_RADIUS;
+
+// Movement
+export const MOVE_SPEED = MOVEMENT_SPEED;
+
+// Missiles
+export const MISSILE_RADIUS_PER_DAMAGE = MISSILE_DAMAGE_RADIUS_SCALE;
+
+// Shield (aliases for consistency)
+export const SHIELD_MAX_STRENGTH = SHIELD_MAX_BLOCK;
+export const SHIELD_MIN_STRENGTH = SHIELD_MIN_BLOCK;
+export const SHIELD_DECAY_RATE = SHIELD_DECAY_PER_SECOND;
+
+// Blink (aliases for consistency)
+export const BLINK_MAX_RANGE = BLINK_RANGE;
+
+/**
+ * Calculate blink cooldown based on distance traveled.
+ * Short blinks get short cooldowns, full-range blinks get the maximum.
+ */
+export function calculateBlinkCooldown(distance: number): number
+{
+	const ratio = Math.min(1, distance / BLINK_MAX_RANGE);
+	return Math.max(BLINK_MIN_COOLDOWN, Math.round(ratio * BLINK_MAX_COOLDOWN));
+}
+
+// Arena
+export const ARENA_WATER_BUFFER = 200; // units - missiles can fly this far past arena bounds