@vibemancer/core 0.1.0

package/src/engine/spells.ts

@@ -0,0 +1,128 @@
+import {WizardState, MissileConfig, ProjectileState} from '../types.js';
+import {
+	SHIELD_MAX_BLOCK,
+	SHIELD_DECAY_PER_SECOND,
+	SHIELD_MIN_BLOCK,
+	TICKS_PER_SECOND,
+	GCD_DURATION,
+	SHIELD_CAST_TIME,
+	BLINK_CAST_TIME,
+	calculateMissileCastTime,
+	calculateWarmupMultiplier,
+} from '../rules.js';
+
+/**
+ * Start casting a spell.
+ * For missiles, applies warmup system (bonus for similar, penalty for switching).
+ */
+export function startCast(wizard: WizardState, spell: 'missile' | 'shield' | 'blink', config?: MissileConfig): void
+{
+	wizard.state = 'casting';
+	wizard.castingSpell = spell;
+	wizard.castProgress = 0;
+
+	if (spell === 'missile' && config)
+	{
+		// calculateMissileCastTime includes warmup when lastMissileConfig is passed
+		const castTimeSec = calculateMissileCastTime(config, wizard.lastMissileConfig);
+		wizard.castDuration = Math.max(1, Math.round(castTimeSec * TICKS_PER_SECOND));
+		// Store warmup multiplier for visualization
+		wizard.warmupMultiplier = calculateWarmupMultiplier(wizard.lastMissileConfig, config);
+	}
+	else if (spell === 'shield')
+	{
+		wizard.castDuration = SHIELD_CAST_TIME;
+	}
+	else if (spell === 'blink')
+	{
+		wizard.castDuration = BLINK_CAST_TIME;
+	}
+}
+
+/**
+ * Cancel the current cast.
+ */
+export function cancelCast(wizard: WizardState): void
+{
+	wizard.state = 'idle';
+	delete wizard.castingSpell;
+	delete wizard.castProgress;
+	delete wizard.castDuration;
+}
+
+/**
+ * Complete the current cast and trigger the spell effect.
+ */
+export function completeCast(wizard: WizardState): void
+{
+	const spell = wizard.castingSpell;
+
+	if (spell === 'shield')
+	{
+		wizard.state = 'channeling';
+		wizard.channelingSpell = 'shield';
+		wizard.channelDuration = 0;
+	}
+	else if (spell === 'missile')
+	{
+		wizard.state = 'gcd_locked';
+		wizard.gcdRemaining = GCD_DURATION;
+	}
+	else
+	{
+		// Blink: no GCD — can act immediately after teleporting
+		wizard.state = 'idle';
+	}
+
+	delete wizard.castingSpell;
+	delete wizard.castProgress;
+	delete wizard.castDuration;
+}
+
+/**
+ * Update the shield channel state.
+ */
+export function updateShield(wizard: WizardState, deltaTicks: number): void
+{
+	if (wizard.state === 'channeling' && wizard.channelingSpell === 'shield')
+	{
+		wizard.channelDuration = (wizard.channelDuration ?? 0) + deltaTicks;
+	}
+}
+
+/**
+ * Calculate the current block percentage of a shield based on channel duration.
+ */
+export function calculateShieldBlock(channelDurationTicks: number): number
+{
+	const channelSeconds = channelDurationTicks / TICKS_PER_SECOND;
+	const decay = channelSeconds * SHIELD_DECAY_PER_SECOND;
+	return Math.max(SHIELD_MIN_BLOCK, SHIELD_MAX_BLOCK - decay);
+}
+
+/**
+ * Apply damage to a wizard, considering shield mitigation.
+ *
+ * Shield blocks a percentage of damage based on channel duration:
+ * - Fresh shield (0s): 90% block → 10% damage through
+ * - Decayed shield: block % decreases over time (20%/sec)
+ * - Minimum: 30% block → 70% damage through
+ *
+ * (Design doc lines 196-212)
+ */
+export function applyDamage(wizard: WizardState, damage: number, _projectile?: ProjectileState): number
+{
+	if (wizard.invincible) return 0;
+
+	let finalDamage = damage;
+
+	if (wizard.state === 'channeling' && wizard.channelingSpell === 'shield')
+	{
+		const blockPercent = calculateShieldBlock(wizard.channelDuration ?? 0);
+		// Simple block: damage through = damage * (1 - blockPercent)
+		finalDamage = damage * (1 - blockPercent);
+	}
+
+	wizard.health = Math.max(0, wizard.health - finalDamage);
+	return finalDamage;
+}

package/src/engine-version.ts

@@ -0,0 +1,11 @@
+/**
+ * Engine version — milliseconds since the Unix epoch.
+ *
+ * Bumped automatically by `scripts/update-engine-version.mjs` on every build.
+ * The same value is propagated to `packages/functions/src/engine-version.generated.ts`
+ * so cloud functions and the core engine always agree on a single version per deploy.
+ *
+ * Used to gate spectator replays: a recorded match can only be re-simulated when
+ * the runtime engine version matches the version that produced the match.
+ */
+export const ENGINE_VERSION = 1777556890699;

package/src/hooks/action-builders.ts

@@ -0,0 +1,210 @@
+/**
+ * VIBEMANCER - ACTION BUILDERS
+ *
+ * Fluent API for constructing bot actions with type-safe chaining.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Movement:   direction vector, magnitude auto-normalized to max 100
+ *   Speed:      units per tick (player moves at 1 unit/tick = 100 units/sec)
+ *   Duration:   ticks (divide by 100 for seconds)
+ *   Angles:     degrees (0°=right, 90°=down, 180°=left, 270°=up)
+ *   Damage:     raw HP removed on hit (wizard has 60 HP)
+ *   Turn rate:  degrees per tick the missile can rotate
+ */
+
+import {WizardActions, MissileConfig, MissileAIFunction} from '../types.js';
+import type {FinalAction, ActionBuilder} from './types.js';
+
+/**
+ * Create a FinalAction (no further chaining possible).
+ */
+function createFinalAction(action: WizardActions): FinalAction
+{
+	return {
+		_toAction: () => action,
+	};
+}
+
+/**
+ * Create an ActionBuilder (can chain .move()).
+ */
+function createActionBuilder(baseAction: Omit<WizardActions, 'move'>): ActionBuilder
+{
+	const action: WizardActions = {
+		...baseAction,
+		move: {x: 0, y: 0},
+	};
+
+	return {
+		_toAction: () => action,
+		move(x: number, y: number): FinalAction
+		{
+			return createFinalAction({
+				...action,
+				move: {x, y},
+			});
+		},
+	};
+}
+
+// ============================================================
+// ACTION BUILDERS
+// ============================================================
+
+/**
+ * Channel a shield that blocks incoming damage.
+ *
+ * Starts at 90% block, decays by 20% per second, minimum 30%.
+ * Takes 20 ticks (0.2s) to activate. Movement is disabled while channeling.
+ * Cancel anytime with cancel(). Triggers 100-tick (1s) GCD after cancel.
+ *
+ * Can chain .move() — movement applies during the 20-tick cast, NOT during channel.
+ *
+ * @example
+ *   return shield();                    // shield and stay still
+ *   return shield().move(100, 0);       // move right while cast starts
+ */
+export function shield(): ActionBuilder
+{
+	return createActionBuilder({
+		startCast: {spell: 'shield'},
+	});
+}
+
+/**
+ * Cast a missile spell.
+ *
+ * Cast time scales with damage, speed, duration, and turn rate — bigger missiles
+ * take longer to cast. While casting you move at 50% speed. After firing, 100-tick
+ * (1s) GCD before next spell.
+ *
+ * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
+ * incurs a 20% penalty.
+ *
+ * Can chain .move() for simultaneous movement while casting.
+ *
+ * @param config - Missile stats:
+ *   - damage:   HP removed on hit (1-60 typical). Also sets hitbox: radius = 2 + 0.1×damage.
+ *   - speed:    units/tick (min 1.5). Player moves at 1 u/t, so 5 = 5× player speed.
+ *   - duration: ticks the missile lives (min 10). Range ≈ speed × duration.
+ *   - turnRate: degrees/tick of homing (0 = straight line, 3 = moderate homing, 5+ = strong).
+ *              Negative = no homing + minor speed cost reduction.
+ * @param ai - Called every tick to control missile steering. Receives:
+ *   - missileState: the missile's position, rotation (degrees), speed, remainingTicks
+ *   - worldState:   full game state (all wizards, projectiles)
+ *   - random():     seeded PRNG [0, 1)
+ *   Return { turnToward: {x, y} } to home toward a position, or {} to fly straight.
+ * @param direction - Launch angle in degrees (0°=right, 90°=down, 180°=left, 270°=up).
+ *   Tip: use Math.atan2(dy, dx) * (180 / Math.PI) to aim at a target.
+ *
+ * @example
+ *   // Straight missile aimed at enemy
+ *   const angle = Math.atan2(dy, dx) * (180 / Math.PI);
+ *   return missile({damage: 15, speed: 6, duration: 200, turnRate: 0}, () => ({}), angle);
+ *
+ *   // Homing missile that tracks enemy
+ *   return missile(
+ *     {damage: 10, speed: 5, duration: 300, turnRate: 3},
+ *     ({worldState}) => ({turnToward: worldState.enemies[0]?.position}),
+ *     angle,
+ *   );
+ */
+export function missile(config: MissileConfig, ai: MissileAIFunction, direction: number): ActionBuilder
+{
+	return createActionBuilder({
+		startCast: {
+			spell: 'missile',
+			config,
+			missileAI: ai,
+			direction,
+		},
+	});
+}
+
+/**
+ * Teleport to an absolute position on the arena.
+ *
+ * Max range: 300 units from current position (clamped by engine if further).
+ * Cast time: 10 ticks (0.1s). Cooldown scales with distance:
+ *   - 100 units → 100 ticks (1s)
+ *   - 300 units → 2000 ticks (20s)
+ *
+ * Cannot chain .move() — blink IS the movement.
+ *
+ * @param x - Target X position (0-800, absolute world coordinate)
+ * @param y - Target Y position (0-800, absolute world coordinate)
+ *
+ * @example
+ *   return blink(400, 400);                              // blink to center
+ *   return blink(enemy.position.x, enemy.position.y);    // blink to enemy
+ */
+export function blink(x: number, y: number): FinalAction
+{
+	return createFinalAction({
+		move: {x: 0, y: 0}, // No manual movement with blink
+		startCast: {
+			spell: 'blink',
+			target: {x, y},
+		},
+	});
+}
+
+/**
+ * Cancel current cast or channel (e.g. stop shielding to attack).
+ *
+ * Canceling a cast/channel triggers 100-tick (1s) GCD.
+ * Can chain .move() for simultaneous movement.
+ *
+ * @example
+ *   return cancel().move(-100, 0);  // cancel and dodge left
+ */
+export function cancel(): ActionBuilder
+{
+	return createActionBuilder({
+		cancel: true,
+	});
+}
+
+/**
+ * Move in a direction without casting any spell.
+ *
+ * This is a **direction vector**, not a target position. The engine normalizes
+ * the magnitude to max 100, then moves at 1 unit/tick (100 units/sec).
+ * Positive X = right, positive Y = down.
+ *
+ * To move toward a target position, subtract your position:
+ *   move(target.x - myPos.x, target.y - myPos.y)
+ *
+ * @param x - Horizontal direction (positive = right, negative = left)
+ * @param y - Vertical direction (positive = down, negative = up)
+ *
+ * @example
+ *   return move(100, 0);                                       // move right
+ *   return move(enemy.position.x - myPos.x, enemy.position.y - myPos.y);  // move toward enemy
+ */
+export function move(x: number, y: number): FinalAction
+{
+	return createFinalAction({
+		move: {x, y},
+	});
+}
+
+/**
+ * Do nothing — no action, no movement.
+ */
+export function idle(): FinalAction
+{
+	return createFinalAction({
+		move: {x: 0, y: 0},
+	});
+}
+
+/**
+ * Extract WizardActions from a FinalAction.
+ * Used by the engine to get the actual action.
+ */
+export function extractAction(finalAction: FinalAction): WizardActions
+{
+	return finalAction._toAction();
+}

package/src/hooks/bot-wrapper.ts

@@ -0,0 +1,84 @@
+/**
+ * VIBEMANCER - BOT WRAPPER
+ *
+ * Utilities to convert between old-style (WizardFunction) and new-style (BotFunction) bots.
+ */
+
+import {WizardFunction, WizardActions, GameState, GameConfig} from '../types.js';
+import {withBotContext} from '../engine/hooks-runtime.js';
+import {extractAction} from './action-builders.js';
+import type {BotFunction, BotContext} from './types.js';
+
+/**
+ * Convert a new-style bot (using hooks) to an old-style bot (WizardFunction).
+ *
+ * This allows new bots to work with the existing simulation.
+ *
+ * @example
+ * const NewBot: BotFunction = () => {
+ *   const health = useHealth();
+ *   return health < 10 ? shield() : idle();
+ * };
+ *
+ * // Convert to work with simulate()
+ * const oldStyleBot = wrapNewBot(NewBot);
+ * simulate(oldStyleBot, opponent);
+ */
+export function wrapNewBot(newBot: BotFunction): WizardFunction
+{
+	return ({state, config}: {state: GameState; config: GameConfig; random: () => number}): WizardActions =>
+	{
+		// Create the BotContext from GameState
+		// Note: entityId is inherited from the simulation's outer runWithHooks call
+		const botContext: BotContext = {
+			entityId: 'unused', // Not used - entity ID comes from simulation
+			tick: state.tick,
+			position: state.position,
+			velocity: state.velocity,
+			health: state.health,
+			maxHealth: state.maxHealth,
+			state: state.state,
+			castingSpell: state.castingSpell,
+			castProgress: state.castProgress,
+			castDuration: state.castDuration,
+			channelingSpell: state.channelingSpell,
+			channelDuration: state.channelDuration,
+			gcdRemaining: state.gcdRemaining,
+			blinkCooldown: state.blinkCooldown,
+			enemies: state.enemies.map((e) => ({
+				id: e.id,
+				position: e.position,
+				velocity: e.velocity,
+				health: e.health,
+				state: e.state,
+				castingSpell: e.castingSpell,
+				channelingSpell: e.channelingSpell,
+				channelDuration: e.channelDuration,
+			})),
+			projectiles: state.projectiles,
+			myProjectiles: state.myProjectiles,
+			arenaWidth: config.arenaSize.width,
+			arenaHeight: config.arenaSize.height,
+			damageDealt: state.damageDealt,
+			damageTaken: state.damageTaken,
+			lastHitTick: state.lastHitTick,
+		};
+
+		// Run the new-style bot with context
+		// Use withBotContext (not runBotWithContext) to preserve the entity ID
+		// set by the simulation's outer runWithHooks call
+		const finalAction = withBotContext(botContext, newBot);
+
+		// Extract WizardActions from FinalAction
+		return extractAction(finalAction);
+	};
+}
+
+/**
+ * Type guard to check if a bot is a new-style BotFunction.
+ * New-style bots have 0 parameters, old-style bots have at least 1.
+ */
+export function isNewStyleBot(bot: WizardFunction | BotFunction): bot is BotFunction
+{
+	return bot.length === 0;
+}

package/src/hooks/index.ts

@@ -0,0 +1,75 @@
+/**
+ * VIBEMANCER - HOOKS API
+ *
+ * Main export file for the hooks-based bot API.
+ */
+
+// Types
+export type {
+	EnemyState,
+	AnalyzedThreat,
+	FinalAction,
+	ActionBuilder,
+	BotFunction,
+	BotContext,
+	MissileConfig,
+	MissileAIFunction,
+} from './types.js';
+
+// State hooks
+export {
+	useHealth,
+	usePosition,
+	useVelocity,
+	useStatus,
+	useTicksUntilReady,
+	useShieldStrength,
+	useBlinkCooldown,
+	useCastingSpell,
+	useCastProgress,
+	useEnemy,
+	useMyProjectiles,
+	useDamageDealt,
+	useDamageTaken,
+	useLastHitTick,
+	useArenaSize,
+	useTick,
+	useThreats,
+	useClosestThreat,
+	useMyThreatsToEnemy,
+} from './state-hooks.js';
+
+// Threat analysis (for advanced users who want direct access)
+export {analyzeThreats} from './threat-analysis.js';
+
+// Action builders
+export {
+	shield,
+	missile,
+	blink,
+	cancel,
+	move,
+	idle,
+	extractAction,
+} from './action-builders.js';
+
+// Re-export persistence hooks from runtime
+export {
+	useState,
+	useEffect,
+	useMemo,
+	useRef,
+	runBotWithContext,
+	withBotContext,
+	getBotContext,
+} from '../engine/hooks-runtime.js';
+
+// Re-export RefObject type
+export type {RefObject} from '../engine/hooks-runtime.js';
+
+// Bot wrapper for integration
+export {wrapNewBot, isNewStyleBot} from './bot-wrapper.js';
+
+// Parameter tuning hook
+export {useParam} from '../engine/params-runtime.js';
+export type {ParamDeclaration} from '../engine/params-runtime.js';