@vibemancer/core 0.1.3 → 0.1.5

package/src/rules.ts

@@ -3,49 +3,120 @@
  *
  * This is the single source of truth for all game constants.
  * All game logic imports from here. Read this to understand the game.
+ *
+ * SWEEPABLE CONSTANTS — the balance-search ruleset:
+ * Every combat-balance constant lives on the mutable `RULES` object. The engine
+ * and bots read `RULES.X` so the balance-search optimizer can override any of
+ * them at runtime via applyRulesetOverrides() — object property reads are live
+ * across every module and survive bundling (unlike a reassigned `let`, which
+ * esbuild/Vite snapshot at the import site). Structural constants (arena size,
+ * tick rate, hitbox radius, missile floors) stay plain `const`.
+ *
+ * The UPPER_CASE named exports below (WIZARD_HEALTH, SHIELD_CAST_TIME, …) are
+ * default SNAPSHOTS for external/UI/MCP consumers that only need the factory
+ * value. They do NOT track overrides — anything that must respond to a sweep
+ * reads `RULES.X`.
  */
 
 import {MissileConfig} from './types.js';
 
-// === TIMING ===
+// === TIMING (structural) ===
 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
+/* eslint-disable @typescript-eslint/naming-convention -- keys mirror constant names */
+/**
+ * The mutable ruleset: the single source of truth for every sweepable combat
+ * constant. Engine + bots read these via `RULES.X`. Override with
+ * applyRulesetOverrides(); restore with resetRuleset().
+ */
+export const RULES = {
+	// Wizard
+	WIZARD_HEALTH: 60,
+	MOVEMENT_SPEED: 1.5, // units per tick (150 units/sec)
+	CASTING_MOVEMENT_MULT: 0.33, // 33% speed while casting
+
+	// GCD
+	GCD_DURATION: 100, // ticks (1 second)
+
+	// Shield
+	SHIELD_CAST_TIME: 20, // ticks (0.2s)
+	SHIELD_MAX_BLOCK: 0.9, // 90%
+	SHIELD_DECAY_PER_SECOND: 0.2, // loses 20% per second
+	SHIELD_MIN_BLOCK: 0.3, // 30% minimum
+
+	// Blink
+	BLINK_CAST_TIME: 10, // ticks (0.1s)
+	BLINK_RANGE: 300, // units
+	BLINK_MAX_COOLDOWN: 2000, // ticks (20 seconds) — full-range blink
+	BLINK_MIN_COOLDOWN: 100, // ticks (1 second) — micro-blink floor
+
+	// Knockback
+	KNOCKBACK_DAMAGE_THRESHOLD: 10, // damage above this causes knockback
+	KNOCKBACK_SPEED_PER_DAMAGE: 2, // knockback speed per damage over threshold
+	KNOCKBACK_DELAY: 5, // ticks before the impulse applies (explosion expand)
+	KNOCKBACK_DECAY: 0.7, // per-tick knockback velocity decay
+
+	// Missile cast-time formula
+	MISSILE_MIN_CAST_TIME: 0.1, // seconds
+	MISSILE_BASE_RADIUS: 2, // base hitbox radius in units
+	MISSILE_DAMAGE_RADIUS_SCALE: 0.1, // additional radius per damage point
+	MISSILE_BASE_CAST: 0.1,
+	MISSILE_DAMAGE_SCALE: 0.226,
+	MISSILE_DAMAGE_POWER: 2 / 3, // sublinear: DPS always increases with damage
+	MISSILE_HOMING_COEFF: 0.12,
+	MISSILE_TURN_DURATION_COEFF: 0.10,
+	MISSILE_SPEED_DURATION_BASELINE: 1.5,
+	MISSILE_SPEED_DURATION_COEFF: 0.025,
+
+	// Cast warmup
+	WARMUP_MAX_BONUS: 0.20, // 20% cast time reduction at full warmup
+	WARMUP_MAX_PENALTY: 0.20, // 20% cast time increase when switching
+};
+/* eslint-enable @typescript-eslint/naming-convention */
+
+// === WIZARD (default snapshots — engine/bots read RULES.X) ===
+export const WIZARD_HEALTH = RULES.WIZARD_HEALTH;
+export const WIZARD_RADIUS = 5; // units (structural — hitbox)
+export const MOVEMENT_SPEED = RULES.MOVEMENT_SPEED;
+export const CASTING_MOVEMENT_MULT = RULES.CASTING_MOVEMENT_MULT;
 
 // === GCD ===
-export const GCD_DURATION = 100; // ticks (1 second)
+export const GCD_DURATION = RULES.GCD_DURATION;
 
 // === 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
+export const SHIELD_CAST_TIME = RULES.SHIELD_CAST_TIME;
+export const SHIELD_MAX_BLOCK = RULES.SHIELD_MAX_BLOCK;
+export const SHIELD_DECAY_PER_SECOND = RULES.SHIELD_DECAY_PER_SECOND;
+export const SHIELD_MIN_BLOCK = RULES.SHIELD_MIN_BLOCK;
 // 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
+export const BLINK_CAST_TIME = RULES.BLINK_CAST_TIME;
+export const BLINK_RANGE = RULES.BLINK_RANGE;
+export const BLINK_MAX_COOLDOWN = RULES.BLINK_MAX_COOLDOWN; // full-range blink
+export const BLINK_MIN_COOLDOWN = RULES.BLINK_MIN_COOLDOWN; // 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 BLINK_COOLDOWN = RULES.BLINK_MAX_COOLDOWN;
+
+// === KNOCKBACK ===
+export const KNOCKBACK_DAMAGE_THRESHOLD = RULES.KNOCKBACK_DAMAGE_THRESHOLD;
+export const KNOCKBACK_SPEED_PER_DAMAGE = RULES.KNOCKBACK_SPEED_PER_DAMAGE;
+export const KNOCKBACK_DELAY = RULES.KNOCKBACK_DELAY;
+export const KNOCKBACK_DECAY = RULES.KNOCKBACK_DECAY;
+
+// === ARENA (structural) ===
+export const ARENA_SIZE = 860;
+export const LAVA_BORDER_WIDTH = 30;
+export const ARENA_MIN = LAVA_BORDER_WIDTH; // playfield starts here (30)
+export const ARENA_MAX = ARENA_SIZE - LAVA_BORDER_WIDTH; // playfield ends here (830)
 export const SPAWN_DISTANCE = 600;
 
-// === MISSILE CONSTRAINTS ===
+// === MISSILE CONSTRAINTS (structural) ===
 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
+export const MISSILE_MIN_CAST_TIME = RULES.MISSILE_MIN_CAST_TIME;
 
 // === MISSILE HITBOX ===
 // Missile hitbox scales with damage (design doc line 1122)
@@ -54,15 +125,15 @@ export const MISSILE_MIN_CAST_TIME = 0.1; // seconds
 // - 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
+export const MISSILE_BASE_RADIUS = RULES.MISSILE_BASE_RADIUS;
+export const MISSILE_DAMAGE_RADIUS_SCALE = RULES.MISSILE_DAMAGE_RADIUS_SCALE;
 
 /**
  * Calculate missile hitbox radius based on damage.
  */
 export function calculateMissileRadius(damage: number): number
 {
-	return MISSILE_BASE_RADIUS + damage * MISSILE_DAMAGE_RADIUS_SCALE;
+	return (RULES.MISSILE_BASE_RADIUS + damage * RULES.MISSILE_DAMAGE_RADIUS_SCALE) * 3;
 }
 
 // === MISSILE CAST TIME FORMULA ===
@@ -77,27 +148,21 @@ export function calculateMissileRadius(damage: number): number
 //   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;
+export const MISSILE_BASE_CAST = RULES.MISSILE_BASE_CAST;
+export const MISSILE_DAMAGE_SCALE = RULES.MISSILE_DAMAGE_SCALE;
+export const MISSILE_DAMAGE_POWER = RULES.MISSILE_DAMAGE_POWER; // sublinear: DPS always increases with damage
+export const MISSILE_HOMING_COEFF = RULES.MISSILE_HOMING_COEFF;
+export const MISSILE_TURN_DURATION_COEFF = RULES.MISSILE_TURN_DURATION_COEFF;
+export const MISSILE_SPEED_DURATION_BASELINE = RULES.MISSILE_SPEED_DURATION_BASELINE;
+export const MISSILE_SPEED_DURATION_COEFF = RULES.MISSILE_SPEED_DURATION_COEFF;
 
 /**
  * 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.
+ * Higher turn rate = more expensive cast. Negative values clamped to 0.
  */
 export function effectiveTurnRateCost(turnRate: number): number
 {
-	if (turnRate >= 0) return turnRate;
-	const abs = Math.abs(turnRate);
-	return -(abs / (1 + abs));
+	return Math.max(0, turnRate);
 }
 
 /**
@@ -109,7 +174,7 @@ 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
+		turnRate: Math.max(0, Number.isFinite(config.turnRate) ? config.turnRate : 0),
 		duration: Math.max(MISSILE_MIN_DURATION, Number.isFinite(config.duration) ? Math.floor(config.duration) : MISSILE_MIN_DURATION),
 	};
 }
@@ -124,7 +189,7 @@ export function validateMissileConfig(config: MissileConfig): MissileConfig
  *           + 0.10 × (effectiveTurnRateCost(turnRate) × durationSeconds)
  *           + 0.025 × (speed × durationSeconds - 1.5)
  *
- * effectiveTurnRateCost: linear for positive, -ln(1+|t|) for negative (diminishing returns).
+ * turnRate is clamped to >= 0. Cost is linear.
  *
  * If lastMissileConfig is a MissileConfig, applies warmup multiplier:
  * - Similar to previous: up to 20% faster
@@ -136,13 +201,13 @@ export function calculateMissileCastTime(config: MissileConfig, lastMissileConfi
 	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 raw = RULES.MISSILE_BASE_CAST
+		+ RULES.MISSILE_DAMAGE_SCALE * Math.pow(damage, RULES.MISSILE_DAMAGE_POWER)
+		+ RULES.MISSILE_HOMING_COEFF * turnCost
+		+ RULES.MISSILE_TURN_DURATION_COEFF * (turnCost * durationSeconds)
+		+ RULES.MISSILE_SPEED_DURATION_COEFF * (speed * durationSeconds - RULES.MISSILE_SPEED_DURATION_BASELINE);
 
-	const baseCast = Math.max(MISSILE_MIN_CAST_TIME, raw);
+	const baseCast = Math.max(RULES.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,
@@ -152,7 +217,7 @@ export function calculateMissileCastTime(config: MissileConfig, lastMissileConfi
 	if (lastMissileConfig !== null)
 	{
 		const multiplier = calculateWarmupMultiplier(lastMissileConfig, config);
-		return Math.max(MISSILE_MIN_CAST_TIME, baseCast * multiplier);
+		return Math.max(RULES.MISSILE_MIN_CAST_TIME, baseCast * multiplier);
 	}
 
 	return baseCast;
@@ -168,8 +233,8 @@ export function calculateMissileCastTime(config: MissileConfig, lastMissileConfi
 //   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
+export const WARMUP_MAX_BONUS = RULES.WARMUP_MAX_BONUS;
+export const WARMUP_MAX_PENALTY = RULES.WARMUP_MAX_PENALTY;
 // 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.
@@ -190,9 +255,11 @@ export function calculateMissileSimilarity(prev: MissileConfig | undefined, curr
 {
 	if (!prev) return 1; // No previous missile = no conflicting muscle memory = full warmup
 
+	// Stryker disable all: /WARMUP_TURN_TOLERANCE equivalent when tolerance=1 (dividing by 1 = multiplying by 1)
 	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;
+	// Stryker restore all
 
 	return Math.max(0, 1 - dist / 3);
 }
@@ -211,10 +278,10 @@ export function calculateWarmupMultiplier(prev: MissileConfig | undefined, curre
 	// 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);
+	return (1 + RULES.WARMUP_MAX_PENALTY) - similarity * (RULES.WARMUP_MAX_BONUS + RULES.WARMUP_MAX_PENALTY);
 }
 
-// === MATCH ===
+// === MATCH (structural) ===
 export const MATCH_DURATION = 30000; // ticks (5 minutes)
 
 // ============================================================
@@ -223,22 +290,22 @@ export const MATCH_DURATION = 30000; // ticks (5 minutes)
 // ============================================================
 
 // Health & Combat
-export const MAX_HEALTH = WIZARD_HEALTH;
+export const MAX_HEALTH = RULES.WIZARD_HEALTH;
 export const COLLISION_RADIUS = WIZARD_RADIUS;
 
 // Movement
-export const MOVE_SPEED = MOVEMENT_SPEED;
+export const MOVE_SPEED = RULES.MOVEMENT_SPEED;
 
 // Missiles
-export const MISSILE_RADIUS_PER_DAMAGE = MISSILE_DAMAGE_RADIUS_SCALE;
+export const MISSILE_RADIUS_PER_DAMAGE = RULES.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;
+export const SHIELD_MAX_STRENGTH = RULES.SHIELD_MAX_BLOCK;
+export const SHIELD_MIN_STRENGTH = RULES.SHIELD_MIN_BLOCK;
+export const SHIELD_DECAY_RATE = RULES.SHIELD_DECAY_PER_SECOND;
 
 // Blink (aliases for consistency)
-export const BLINK_MAX_RANGE = BLINK_RANGE;
+export const BLINK_MAX_RANGE = RULES.BLINK_RANGE;
 
 /**
  * Calculate blink cooldown based on distance traveled.
@@ -246,9 +313,88 @@ export const BLINK_MAX_RANGE = BLINK_RANGE;
  */
 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));
+	const ratio = Math.min(1, distance / RULES.BLINK_RANGE);
+	return Math.max(RULES.BLINK_MIN_COOLDOWN, Math.round(ratio * RULES.BLINK_MAX_COOLDOWN));
 }
 
 // Arena
 export const ARENA_WATER_BUFFER = 200; // units - missiles can fly this far past arena bounds
+
+// ============================================================
+// RULESET OVERRIDES (for the balance-search optimizer)
+// ============================================================
+//
+// applyRulesetOverrides() mutates the RULES object in place; every engine/bot
+// read of RULES.X sees the new value immediately. Each optimizer worker calls
+// applyRulesetOverrides() before a batch of sims and resetRuleset() after, so a
+// sweep never leaks across evaluations.
+
+/** Factory defaults, snapshotted from the live values at module load (no drift). */
+const RULES_DEFAULTS: Record<string, number> = {...RULES};
+
+/* eslint-disable @typescript-eslint/naming-convention -- keys mirror constant names */
+/**
+ * Search bounds for each sweepable constant. The current value is the start.
+ * Every key here is read by the engine/bots through `RULES.X`, so overrides
+ * take effect across the whole simulation.
+ */
+export const RULESET_RANGES: Record<string, {min: number; max: number}> = {
+	// Wizard
+	WIZARD_HEALTH: {min: 30, max: 120},
+	MOVEMENT_SPEED: {min: 0.75, max: 3},
+	CASTING_MOVEMENT_MULT: {min: 0, max: 1},
+	// GCD
+	GCD_DURATION: {min: 50, max: 200},
+	// Shield
+	SHIELD_CAST_TIME: {min: 5, max: 60},
+	SHIELD_MAX_BLOCK: {min: 0.5, max: 0.95},
+	SHIELD_DECAY_PER_SECOND: {min: 0, max: 0.6},
+	SHIELD_MIN_BLOCK: {min: 0, max: 0.6},
+	// Blink
+	BLINK_CAST_TIME: {min: 2, max: 40},
+	BLINK_RANGE: {min: 150, max: 500},
+	BLINK_MAX_COOLDOWN: {min: 500, max: 4000},
+	BLINK_MIN_COOLDOWN: {min: 20, max: 400},
+	// Knockback (anti-melee lever)
+	KNOCKBACK_DAMAGE_THRESHOLD: {min: 0, max: 30},
+	KNOCKBACK_SPEED_PER_DAMAGE: {min: 0, max: 8},
+	KNOCKBACK_DELAY: {min: 0, max: 15},
+	KNOCKBACK_DECAY: {min: 0.3, max: 0.95},
+	// Missile cast-time formula (the core "cast speed" balance lever)
+	MISSILE_BASE_CAST: {min: 0, max: 0.5},
+	MISSILE_DAMAGE_SCALE: {min: 0.1, max: 0.5},
+	MISSILE_DAMAGE_POWER: {min: 0.4, max: 1},
+	MISSILE_HOMING_COEFF: {min: 0, max: 0.4},
+	MISSILE_TURN_DURATION_COEFF: {min: 0, max: 0.3},
+	MISSILE_SPEED_DURATION_BASELINE: {min: 0.5, max: 3},
+	MISSILE_SPEED_DURATION_COEFF: {min: 0, max: 0.1},
+	MISSILE_MIN_CAST_TIME: {min: 0.05, max: 0.5},
+	// Missile hitbox
+	MISSILE_BASE_RADIUS: {min: 0.5, max: 5},
+	MISSILE_DAMAGE_RADIUS_SCALE: {min: 0, max: 0.3},
+	// Warmup
+	WARMUP_MAX_BONUS: {min: 0, max: 0.5},
+	WARMUP_MAX_PENALTY: {min: 0, max: 0.5},
+};
+/* eslint-enable @typescript-eslint/naming-convention */
+
+/** Merge overrides onto the RULES object and apply them globally. */
+export function applyRulesetOverrides(overrides: Record<string, number>): void
+{
+	for (const [key, value] of Object.entries(overrides))
+	{
+		if (key in RULES) (RULES as Record<string, number>)[key] = value;
+	}
+}
+
+/** Restore all swept constants to their factory defaults. */
+export function resetRuleset(): void
+{
+	Object.assign(RULES, RULES_DEFAULTS);
+}
+
+/** Current value of every sweepable constant (the optimizer's starting point). */
+export function currentRuleset(): Record<string, number>
+{
+	return {...RULES};
+}

package/src/stats.ts

@@ -7,7 +7,7 @@
 
 import type {GameState} from './types.js';
 import type {SimulateResult} from './engine/simulation.js';
-import {TICKS_PER_SECOND, SHIELD_MAX_BLOCK, SHIELD_DECAY_PER_SECOND, SHIELD_MIN_BLOCK} from './rules.js';
+import {RULES, TICKS_PER_SECOND} from './rules.js';
 
 /** Detailed statistics for one bot in a single match. */
 export interface FightStats
@@ -67,7 +67,7 @@ export interface FightStats
 function shieldBlockPct(channelDurationTicks: number): number
 {
 	const channelSec = channelDurationTicks / TICKS_PER_SECOND;
-	return Math.max(SHIELD_MIN_BLOCK, SHIELD_MAX_BLOCK - SHIELD_DECAY_PER_SECOND * channelSec);
+	return Math.max(RULES.SHIELD_MIN_BLOCK, RULES.SHIELD_MAX_BLOCK - RULES.SHIELD_DECAY_PER_SECOND * channelSec);
 }
 
 /**

package/src/testing.ts

@@ -14,11 +14,9 @@
  * });
  */
 
-import type {BotFunction} from './hooks/types.js';
-import type {WizardFunction} from './types.js';
+import type {WizardFunction} from './hooks/types.js';
 import type {FightResult, SimulateResult, MatchWinner, FightWinner} from './engine/simulation.js';
 import {fight, simulate, FIGHT_SPAWN_DISTANCES} from './engine/simulation.js';
-import {isNewStyleBot, wrapNewBot} from './hooks/bot-wrapper.js';
 import {extractStats} from './stats.js';
 import type {FightStats} from './stats.js';
 
@@ -97,34 +95,14 @@ export interface TestBotBuilder
 function resolveBuiltinBot(name: string): WizardFunction
 {
 	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- dynamic bot lookup
-	const botMap = allBots as unknown as Record<string, WizardFunction | BotFunction>;
+	const botMap = allBots as unknown as Record<string, WizardFunction>;
 	const bot = botMap[name];
 	if (!bot)
 	{
 		const available = Object.keys(botMap).filter((k) => typeof botMap[k] === 'function').join(', ');
 		throw new Error(`Unknown opponent "${name}". Available bots: ${available}`);
 	}
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- branching on length+shape detection
-	return typeof bot === 'function' && bot.length === 0 && isNewStyleBot(bot as BotFunction)
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- guarded by isNewStyleBot above
-		? wrapNewBot(bot as BotFunction)
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- legacy style bot after guard
-		: bot as WizardFunction;
-}
-
-/**
- * Wrap a bot function for use with the simulation engine.
- */
-function wrapBot(bot: WizardFunction | BotFunction): WizardFunction
-{
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- runtime shape detection
-	if (isNewStyleBot(bot as BotFunction))
-	{
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- guarded by isNewStyleBot above
-		return wrapNewBot(bot as BotFunction);
-	}
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- legacy style bot after guard
-	return bot as WizardFunction;
+	return bot;
 }
 
 /**
@@ -155,15 +133,13 @@ function wrapBot(bot: WizardFunction | BotFunction): WizardFunction
  * });
  * ```
  */
-export function testBot(bot: WizardFunction | BotFunction): TestBotBuilder
+export function testBot(bot: WizardFunction): TestBotBuilder
 {
-	const wrappedBot = wrapBot(bot);
-
 	return {
 		fight(opponent: string, options?: {seed?: number}): TestFightResult
 		{
 			const opponentBot = resolveBuiltinBot(opponent);
-			const raw = fight(wrappedBot, opponentBot, {seed: options?.seed});
+			const raw = fight(bot, opponentBot, {seed: options?.seed});
 
 			return {
 				raw,
@@ -184,7 +160,7 @@ export function testBot(bot: WizardFunction | BotFunction): TestBotBuilder
 		}): TestSimulateResult
 		{
 			const opponentBot = resolveBuiltinBot(opponent);
-			const raw = simulate(wrappedBot, opponentBot, {
+			const raw = simulate(bot, opponentBot, {
 				seed: options?.seed,
 				spawnDistance: options?.spawnDistance ?? FIGHT_SPAWN_DISTANCES[2], // 600 (middle distance)
 				maxTicks: options?.maxTicks,

package/src/trace.ts

@@ -11,7 +11,7 @@
  * - User tests that want event-level analysis
  */
 
-import type {GameState, ProjectileState} from './types.js';
+import type {GameState, ProjectileState, SimEvent} from './types.js';
 import type {SimulateResult, BotError} from './engine/simulation.js';
 import {distanceTo} from './utils/distance.js';
 
@@ -31,6 +31,11 @@ export type TraceEventType =
 	| 'FIRE'         // Missile launched (includes config + range)
 	| 'HIT'          // Damage dealt to opponent
 	| 'HURT'         // Damage taken from opponent
+	| 'DEATH'        // Wizard killed (missile hit)
+	| 'LAVA_DEATH'   // Wizard killed by lava (knockback/walk into border)
+	| 'SHIELD_BLOCK' // Shield absorbed damage (shows blocked + through amounts)
+	| 'KNOCKBACK'    // Knocked back by missile impact
+	| 'BLINK'        // Blink teleport (from → to positions)
 	| 'DODGE_START'  // Enemy missile enters 150u proximity
 	| 'DODGE_CLOSE'  // Enemy missile enters 50u proximity
 	| 'MOVE'         // Movement summary (every 100 ticks)
@@ -58,6 +63,7 @@ export interface TraceBotSummary
 	shields: number;
 	blinks: number;
 	dodgeEncounters: number;
+	causeOfDeath: 'missile' | 'lava' | 'alive' | 'timeout';
 	movement: {strafe: number; approach: number; retreat: number; still: number};
 }
 
@@ -189,6 +195,41 @@ export function extractTraceEvents(history: GameState[], errors?: BotError[]): T
 			}
 		}
 
+		// --- Simulation events (death, lava, shield block, knockback, blink) ---
+		if (state.events)
+		{
+			for (const ev of state.events)
+			{
+				const actor = actorFromId(ev);
+				if (ev.type === 'wizard-death')
+				{
+					events.push({tick, actor, type: 'DEATH', detail: `killed at (${ev.position.x.toFixed(0)},${ev.position.y.toFixed(0)})`});
+				}
+				else if (ev.type === 'wizard-lava-death')
+				{
+					events.push({tick, actor, type: 'LAVA_DEATH', detail: `walked/knocked into lava at (${ev.position.x.toFixed(0)},${ev.position.y.toFixed(0)})`});
+				}
+				else if (ev.type === 'shield-block')
+				{
+					events.push({tick, actor, type: 'SHIELD_BLOCK', detail: `blocked ${ev.damageBlocked.toFixed(1)} (${ev.damageThrough.toFixed(1)} through)`});
+				}
+				else if (ev.type === 'missile-hit')
+				{
+					const target = ev.targetId === 'wizard-1' ? 'W1' : 'W2';
+					const owner = ev.ownerId === 'wizard-1' ? 'W1' : 'W2';
+					if (ev.actualDamage < ev.damage)
+					{
+						events.push({tick, actor: target, type: 'HURT', detail: `hit by ${owner} missile: ${ev.damage} raw → ${ev.actualDamage.toFixed(1)} actual (shielded) dist=${distance.toFixed(0)}`});
+					}
+				}
+				else if (ev.type === 'blink')
+				{
+					const blinkDist = distanceTo(ev.from, ev.to);
+					events.push({tick, actor, type: 'BLINK', detail: `(${ev.from.x.toFixed(0)},${ev.from.y.toFixed(0)}) → (${ev.to.x.toFixed(0)},${ev.to.y.toFixed(0)}) ${blinkDist.toFixed(0)}u`});
+				}
+			}
+		}
+
 		// --- Movement summary every 100 ticks ---
 		if (tick > 0 && tick % 100 === 0)
 		{
@@ -265,6 +306,10 @@ export function summarizeTrace(
 			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,
+			causeOfDeath: myEvents.some((e) => e.type === 'LAVA_DEATH') ? 'lava'
+				: myEvents.some((e) => e.type === 'DEATH') ? 'missile'
+					: (final && ((actor === 'W1' ? final.health : final.enemies[0]?.health ?? 0) <= 0)) ? 'missile'
+						: result.winner === null ? 'timeout' : 'alive',
 			movement: {
 				strafe: moveEvents.filter((e) => e.detail.startsWith('STRAFE')).length,
 				approach: moveEvents.filter((e) => e.detail.startsWith('APPROACH')).length,
@@ -309,12 +354,20 @@ export function formatTraceEvents(events: TraceEvent[]): string
 export function formatTraceSummary(summary: TraceSummary): string
 {
 	const {w1Name, w2Name, w1, w2} = summary;
+	function formatBot(name: string, b: TraceBotSummary): string
+	{
+		const hitPct = b.missilesLaunched > 0 ? ((b.hits / b.missilesLaunched) * 100).toFixed(0) : 'N/A';
+		const death = b.causeOfDeath === 'lava' ? ' [LAVA DEATH]'
+			: b.causeOfDeath === 'missile' ? ' [KILLED]'
+				: b.causeOfDeath === 'timeout' ? '' : '';
+		return `  ${name}: ${b.missilesLaunched}m ${b.hits}h (${hitPct}%), ${b.damageDealt.toFixed(1)} dealt, ${b.damageReceived.toFixed(1)} taken, ${b.shields}s ${b.blinks}b${death}`;
+	}
 	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`,
+		formatBot(w1Name, w1),
+		formatBot(w2Name, w2),
 		'',
 		`  ${w1Name} movement: ${w1.movement.approach} approach, ${w1.movement.strafe} strafe, ${w1.movement.retreat} retreat, ${w1.movement.still} still | ${w1.dodgeEncounters} dodge encounters`,
 	];
@@ -413,6 +466,13 @@ function dodgeAngle(wizardVelocity: {x: number; y: number}, missileRotation: num
 	return Math.acos(Math.max(-1, Math.min(1, Math.abs(dot)))) * (180 / Math.PI);
 }
 
+function actorFromId(ev: SimEvent): 'W1' | 'W2'
+{
+	if ('wizardId' in ev) return ev.wizardId === 'wizard-1' ? 'W1' : 'W2';
+	if ('ownerId' in ev) return ev.ownerId === 'wizard-1' ? 'W1' : 'W2';
+	return 'W1';
+}
+
 function classifyMovement(state: GameState, enemy: GameState['enemies'][0], speed: number): string
 {
 	if (speed < 0.1) return 'STILL';