@vibemancer/core 1.0.8 → 1.0.9

package/src/hooks/action-builders.ts

@@ -1,266 +1,299 @@
-/**
- * VIBEMANCER - ACTION BUILDERS
- *
- * Fluent API for constructing bot actions with type-safe chaining.
- *
- * UNITS REFERENCE (100 ticks = 1 second):
- *   Position:   absolute world coordinates, 0-860 on each axis (860×860 arena, of which
- *               the outer 30 units on every side are lethal lava — playfield is [30, 830])
- *   Movement:   direction vector, magnitude clamped to max 1 (speed in [0, 1])
- *   Speed:      units per tick (player moves at 1.5 units/tick = 150 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, MissileActions} from '../types.js';
-import type {FinalAction, ActionBuilder, MissileAction, MissileFunction} 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(1, 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. Use getMissileContext()
- *   to read the missile's state (position, rotation, speed, etc.), the full game
- *   state (worldState), and a seeded PRNG (random). Return turnToward(x, y) to home
- *   toward a position, or flyStraight() 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}, () => flyStraight(), angle);
- *
- *   // Homing missile that tracks enemy
- *   return missile(
- *     {damage: 10, speed: 5, duration: 300, turnRate: 3},
- *     () => {
- *       const ctx = getMissileContext();
- *       const enemy = ctx.worldState.enemies[0];
- *       return enemy ? turnToward(enemy.position.x, enemy.position.y) : flyStraight();
- *     },
- *     angle,
- *   );
- */
-export function missile(config: MissileConfig, ai: MissileFunction, 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(-1, 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. Values are in the
- * range [-1, 1] where 1 = full speed. Larger values (like raw position
- * deltas) are clamped to full speed automatically.
- *
- * @param x - Horizontal direction (positive = right, negative = left)
- * @param y - Vertical direction (positive = down, negative = up)
- *
- * @example
- *   return move(1, 0);                                         // move right at full speed
- *   return move(dx / dist, dy / dist);                         // normalized unit vector = full speed
- *   return move(enemy.position.x - myPos.x, enemy.position.y - myPos.y);  // raw delta = clamped to full speed
- */
-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},
-	});
-}
-
-// ============================================================
-// MISSILE ACTION BUILDERS
-// ============================================================
-
-/**
- * Steer the missile toward a world position.
- * The engine clamps the actual turn to the missile's turnRate.
- *
- * @param x - Target X position (world coordinates)
- * @param y - Target Y position (world coordinates)
- */
-export function turnToward(x: number, y: number): MissileAction
-{
-	return {
-		_toMissileAction: () => ({turnToward: {x, y}}),
-	};
-}
-
-/**
- * Steer the missile toward a specific angle (degrees).
- * The engine clamps the actual turn to the missile's turnRate.
- *
- * @param degrees - Target rotation in degrees (0=right, 90=down, 180=left, 270=up)
- */
-export function turnToAngle(degrees: number): MissileAction
-{
-	return {
-		_toMissileAction: () => ({turnToAngle: degrees}),
-	};
-}
-
-/**
- * Fly straight — no steering this tick.
- */
-export function flyStraight(): MissileAction
-{
-	return {
-		_toMissileAction: () => ({}),
-	};
-}
-
-/**
- * Extract MissileActions from a MissileAction.
- * Used by the engine to get the actual missile action.
- */
-export function extractMissileAction(action: MissileAction): MissileActions
-{
-	return action._toMissileAction();
-}
-
-// ============================================================
-// WIZARD ACTION EXTRACTION
-// ============================================================
-
-/**
- * Extract WizardActions from a FinalAction.
- * Used by the engine to get the actual action.
- */
-export function extractAction(finalAction: FinalAction): WizardActions
-{
-	return finalAction._toAction();
-}
+/**
+ * VIBEMANCER - ACTION BUILDERS
+ *
+ * Fluent API for constructing bot actions with type-safe chaining.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-860 on each axis (860×860 arena, of which
+ *               the outer 30 units on every side are lethal lava — playfield is [30, 830])
+ *   Movement:   direction vector, magnitude clamped to max 1 (speed in [0, 1])
+ *   Speed:      units per tick (player moves at 1.5 units/tick = 150 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, MissileActions} from '../types.js';
+import type {FinalAction, ActionBuilder, MissileAction, MissileFunction} 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},
+			});
+		},
+		lockAim(): ActionBuilder
+		{
+			// Opting out of auto-aim for this action. The engine holds `aimDirection` for the
+			// duration of a missile cast, so the angle survives to launch — without this, the
+			// per-tick auto-aim overwrites it and the shot goes at the enemy instead.
+			//
+			// Nothing happens if the action names no direction: there is no angle to keep, and
+			// silently facing 0 degrees would be worse than doing nothing.
+			const cast = action.startCast;
+			const direction = cast && cast.spell === 'missile' ? cast.direction : undefined;
+			if (direction === undefined || !Number.isFinite(direction)) return createActionBuilder(baseAction);
+			return createActionBuilder({...baseAction, aimDirection: direction});
+		},
+	};
+}
+
+// ============================================================
+// 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(). Cancelling costs NO GCD — you are idle the next tick.
+ *
+ * Can chain .move() — movement applies during the 20-tick cast, NOT during channel.
+ *
+ * @example
+ *   return shield();                    // shield and stay still
+ *   return shield().move(1, 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. Use getMissileContext()
+ *   to read the missile's state (position, rotation, speed, etc.), the full game
+ *   state (worldState), and a seeded PRNG (random). Return turnToward(x, y) to home
+ *   toward a position, or flyStraight() 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}, () => flyStraight(), angle);
+ *
+ *   // Homing missile that tracks enemy
+ *   return missile(
+ *     {damage: 10, speed: 5, duration: 300, turnRate: 3},
+ *     () => {
+ *       const ctx = getMissileContext();
+ *       const enemy = ctx.worldState.enemies[0];
+ *       return enemy ? turnToward(enemy.position.x, enemy.position.y) : flyStraight();
+ *     },
+ *     angle,
+ *   );
+ */
+export function missile(config: MissileConfig, ai: MissileFunction, direction: number): ActionBuilder
+{
+	return createActionBuilder({
+		startCast: {
+			spell: 'missile',
+			config,
+			missileAI: ai,
+			direction,
+		},
+	});
+}
+
+/**
+ * Face a specific direction this tick, instead of auto-aiming at the enemy.
+ *
+ * Useful on its own (turning to cover an approach) and during a cast, where it keeps a
+ * locked shot pointed where you want it. Angles are degrees, 0 = right, 90 = down.
+ *
+ * A non-finite angle is ignored rather than applied, because a NaN rotation propagates into
+ * every position calculation that follows it.
+ */
+export function aim(degrees: number): ActionBuilder
+{
+	return createActionBuilder(Number.isFinite(degrees) ? {aimDirection: degrees} : {});
+}
+
+/**
+ * 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).
+ *
+ * Cancelling costs NO GCD. `gcdRemaining` is set only when a spell COMPLETES; the cancel
+ * handlers just return you to idle, so you can act on the very next tick.
+ *
+ * This said "triggers 100-tick (1s) GCD" and was wrong for as long as anyone can tell. It
+ * matters more than a typo: it makes every defender look 100 ticks slower than they are, so
+ * attacks that appear unpunishable on paper are not. Cancel-then-shield really costs 1 tick
+ * plus the 20-tick shield cast, not 120.
+ * Can chain .move() for simultaneous movement.
+ *
+ * @example
+ *   return cancel().move(-1, 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. Values are in the
+ * range [-1, 1] where 1 = full speed. Larger values (like raw position
+ * deltas) are clamped to full speed automatically.
+ *
+ * @param x - Horizontal direction (positive = right, negative = left)
+ * @param y - Vertical direction (positive = down, negative = up)
+ *
+ * @example
+ *   return move(1, 0);                                         // move right at full speed
+ *   return move(dx / dist, dy / dist);                         // normalized unit vector = full speed
+ *   return move(enemy.position.x - myPos.x, enemy.position.y - myPos.y);  // raw delta = clamped to full speed
+ */
+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},
+	});
+}
+
+// ============================================================
+// MISSILE ACTION BUILDERS
+// ============================================================
+
+/**
+ * Steer the missile toward a world position.
+ * The engine clamps the actual turn to the missile's turnRate.
+ *
+ * @param x - Target X position (world coordinates)
+ * @param y - Target Y position (world coordinates)
+ */
+export function turnToward(x: number, y: number): MissileAction
+{
+	return {
+		_toMissileAction: () => ({turnToward: {x, y}}),
+	};
+}
+
+/**
+ * Steer the missile toward a specific angle (degrees).
+ * The engine clamps the actual turn to the missile's turnRate.
+ *
+ * @param degrees - Target rotation in degrees (0=right, 90=down, 180=left, 270=up)
+ */
+export function turnToAngle(degrees: number): MissileAction
+{
+	return {
+		_toMissileAction: () => ({turnToAngle: degrees}),
+	};
+}
+
+/**
+ * Fly straight — no steering this tick.
+ */
+export function flyStraight(): MissileAction
+{
+	return {
+		_toMissileAction: () => ({}),
+	};
+}
+
+/**
+ * Extract MissileActions from a MissileAction.
+ * Used by the engine to get the actual missile action.
+ */
+export function extractMissileAction(action: MissileAction): MissileActions
+{
+	return action._toMissileAction();
+}
+
+// ============================================================
+// WIZARD ACTION EXTRACTION
+// ============================================================
+
+/**
+ * Extract WizardActions from a FinalAction.
+ * Used by the engine to get the actual action.
+ */
+export function extractAction(finalAction: FinalAction): WizardActions
+{
+	return finalAction._toAction();
+}