@vibemancer/core 1.0.7 → 1.0.9

package/src/hooks/types.ts

@@ -1,200 +1,216 @@
-/**
- * VIBEMANCER - HOOKS API TYPES
- *
- * Types for the hooks-based bot API.
- *
- * UNITS REFERENCE (100 ticks = 1 second):
- *   Position:   absolute world coordinates, 0-860 on each axis. The arena is 860x860,
- *               but only [30, 830] is safe — the outer 30 units are lethal lava.
- *   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, WizardActions, GameState, MissileActions} 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;
-	/** Cast progress in ticks (0 if not casting). */
-	castProgress: number;
-	/** Total cast duration in ticks (0 if not casting). */
-	castDuration: number;
-	/** Remaining GCD ticks (0 if not in GCD). */
-	gcdRemaining: number;
-	/** Duration the enemy has been channeling in ticks (0 if not channeling). */
-	channelDuration: number;
-	/** 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;
-}
-
-/**
- * Wizard function type for the hooks API.
- * Called every tick. Read state with hooks, return an action.
- */
-export type WizardFunction = () => FinalAction;
-
-/**
- * Internal context for game state hooks.
- */
-export interface WizardContext
-{
-	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;
-	lastMissileConfig?: MissileConfig;
-	enemies: Array<{
-		id: string;
-		position: Position;
-		velocity: Velocity;
-		health: number;
-		state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
-		castingSpell?: 'missile' | 'shield' | 'blink';
-		castProgress?: number;
-		castDuration?: number;
-		gcdRemaining?: number;
-		channelingSpell?: 'shield';
-		channelDuration?: number;
-	}>;
-	projectiles: ProjectileState[];
-	myProjectiles: ProjectileState[];
-	arenaWidth: number;
-	arenaHeight: number;
-	damageDealt: number;
-	damageTaken: number;
-	lastHitTick: number;
-	random: () => number;
-}
-
-/**
- * Context available to missile AI functions via getMissileContext().
- * Provides missile state, the full game state from the owner's perspective,
- * and a seeded PRNG.
- */
-export interface MissileContext
-{
-	/** Missile position in world coordinates. */
-	position: Position;
-	/** Missile heading in degrees (0=right, 90=down). */
-	rotation: number;
-	/** Missile speed in units/tick. */
-	speed: number;
-	/** Missile turn rate in degrees/tick. */
-	turnRate: number;
-	/** Missile damage on hit. */
-	damage: number;
-	/** Ticks remaining before the missile expires. */
-	remainingTicks: number;
-	/** ID of the wizard who owns this missile. */
-	ownerId: string;
-	/** Full game state from the missile owner's perspective. */
-	worldState: GameState;
-	/** Seeded PRNG [0, 1). Deterministic per missile per tick. */
-	random: () => number;
-}
-
-/**
- * Action returned by a missile AI function.
- * Call turnToward(x, y) to steer, or flyStraight() to coast.
- */
-export interface MissileAction
-{
-	/** Internal: extract the MissileActions */
-	readonly _toMissileAction: () => MissileActions;
-}
-
-/**
- * Missile AI function type for the hooks API.
- * Called every tick for each in-flight missile.
- * Read state with getMissileContext(), return a MissileAction.
- */
-export type MissileFunction = () => MissileAction;
-
-/**
- * Missile configuration for action builders.
- */
-export type {MissileConfig};
+/**
+ * VIBEMANCER - HOOKS API TYPES
+ *
+ * Types for the hooks-based bot API.
+ *
+ * UNITS REFERENCE (100 ticks = 1 second):
+ *   Position:   absolute world coordinates, 0-860 on each axis. The arena is 860x860,
+ *               but only [30, 830] is safe — the outer 30 units are lethal lava.
+ *   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, WizardActions, GameState, MissileActions} 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;
+	/** Cast progress in ticks (0 if not casting). */
+	castProgress: number;
+	/** Total cast duration in ticks (0 if not casting). */
+	castDuration: number;
+	/** Remaining GCD ticks (0 if not in GCD). */
+	gcdRemaining: number;
+	/** Duration the enemy has been channeling in ticks (0 if not channeling). */
+	channelDuration: number;
+	/** 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;
+
+	/**
+	 * Fire at the angle you asked for, instead of auto-aiming at the enemy.
+	 *
+	 * By default a wizard re-aims at the enemy's CURRENT position every tick, and a missile
+	 * launches with the rotation it has when the cast finishes — so the `direction` you pass
+	 * to `missile()` is overwritten before the shot leaves. That makes the enemy impossible
+	 * to LEAD: you always fire where they are, never where they will be.
+	 *
+	 * `lockAim()` holds your angle for the whole cast, which is what makes `getLeadPosition`
+	 * and `interceptAngle` worth using. It is opt-in precisely because auto-aim is the right
+	 * default for most bots: lock your aim and a target that moves during the cast is missed.
+	 *
+	 * Chainable — `missile(cfg, ai, angle).lockAim().move(0, 1)` aims, fires and kites.
+	 */
+	lockAim(): ActionBuilder;
+}
+
+/**
+ * Wizard function type for the hooks API.
+ * Called every tick. Read state with hooks, return an action.
+ */
+export type WizardFunction = () => FinalAction;
+
+/**
+ * Internal context for game state hooks.
+ */
+export interface WizardContext
+{
+	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;
+	lastMissileConfig?: MissileConfig;
+	enemies: Array<{
+		id: string;
+		position: Position;
+		velocity: Velocity;
+		health: number;
+		state: 'idle' | 'casting' | 'channeling' | 'gcd_locked';
+		castingSpell?: 'missile' | 'shield' | 'blink';
+		castProgress?: number;
+		castDuration?: number;
+		gcdRemaining?: number;
+		channelingSpell?: 'shield';
+		channelDuration?: number;
+	}>;
+	projectiles: ProjectileState[];
+	myProjectiles: ProjectileState[];
+	arenaWidth: number;
+	arenaHeight: number;
+	damageDealt: number;
+	damageTaken: number;
+	lastHitTick: number;
+	random: () => number;
+}
+
+/**
+ * Context available to missile AI functions via getMissileContext().
+ * Provides missile state, the full game state from the owner's perspective,
+ * and a seeded PRNG.
+ */
+export interface MissileContext
+{
+	/** Missile position in world coordinates. */
+	position: Position;
+	/** Missile heading in degrees (0=right, 90=down). */
+	rotation: number;
+	/** Missile speed in units/tick. */
+	speed: number;
+	/** Missile turn rate in degrees/tick. */
+	turnRate: number;
+	/** Missile damage on hit. */
+	damage: number;
+	/** Ticks remaining before the missile expires. */
+	remainingTicks: number;
+	/** ID of the wizard who owns this missile. */
+	ownerId: string;
+	/** Full game state from the missile owner's perspective. */
+	worldState: GameState;
+	/** Seeded PRNG [0, 1). Deterministic per missile per tick. */
+	random: () => number;
+}
+
+/**
+ * Action returned by a missile AI function.
+ * Call turnToward(x, y) to steer, or flyStraight() to coast.
+ */
+export interface MissileAction
+{
+	/** Internal: extract the MissileActions */
+	readonly _toMissileAction: () => MissileActions;
+}
+
+/**
+ * Missile AI function type for the hooks API.
+ * Called every tick for each in-flight missile.
+ * Read state with getMissileContext(), return a MissileAction.
+ */
+export type MissileFunction = () => MissileAction;
+
+/**
+ * Missile configuration for action builders.
+ */
+export type {MissileConfig};

package/src/rules.ts

@@ -61,6 +61,11 @@ export const RULES = {
 	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
+	// The real hitbox is THREE TIMES the base+scale figure. This lived as a bare `* 3` inside
+	// calculateMissileRadius, outside RULES, so no document could interpolate it — and five
+	// of them consequently stated the unmultiplied formula, understating the hit window by
+	// 43-57%. It is a rule, so it lives with the rules.
+	MISSILE_RADIUS_MULTIPLIER: 3,
 	MISSILE_BASE_CAST: 0.1,
 	MISSILE_DAMAGE_SCALE: 0.226,
 	MISSILE_DAMAGE_POWER: 2 / 3, // sublinear: DPS always increases with damage
@@ -133,7 +138,7 @@ export const MISSILE_DAMAGE_RADIUS_SCALE = RULES.MISSILE_DAMAGE_RADIUS_SCALE;
  */
 export function calculateMissileRadius(damage: number): number
 {
-	return (RULES.MISSILE_BASE_RADIUS + damage * RULES.MISSILE_DAMAGE_RADIUS_SCALE) * 3;
+	return (RULES.MISSILE_BASE_RADIUS + damage * RULES.MISSILE_DAMAGE_RADIUS_SCALE) * RULES.MISSILE_RADIUS_MULTIPLIER;
 }
 
 // === MISSILE CAST TIME FORMULA ===