@vibemancer/core 1.0.8 → 1.0.9

package/src/hooks/index.ts

@@ -1,83 +1,84 @@
-/**
- * VIBEMANCER - HOOKS API
- *
- * Main export file for the hooks-based bot API.
- */
-
-// Types
-export type {
-	EnemyState,
-	AnalyzedThreat,
-	FinalAction,
-	ActionBuilder,
-	WizardFunction,
-	WizardContext,
-	MissileConfig,
-	MissileContext,
-	MissileAction,
-	MissileFunction,
-} from './types.js';
-
-// State hooks
-export {
-	useRandom,
-	useHealth,
-	usePosition,
-	useVelocity,
-	useStatus,
-	useTicksUntilReady,
-	useShieldStrength,
-	useBlinkCooldown,
-	useCastingSpell,
-	useCastProgress,
-	useEnemy,
-	useProjectiles,
-	useMyProjectiles,
-	useLastMissileConfig,
-	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,
-	turnToward,
-	turnToAngle,
-	flyStraight,
-	extractMissileAction,
-} from './action-builders.js';
-
-// Re-export persistence hooks from runtime
-export {
-	useState,
-	useEffect,
-	useMemo,
-	useRef,
-	runWizardWithContext,
-	withWizardContext,
-	withMissileContext,
-	getWizardContext,
-	getMissileContext,
-} from '../engine/hooks-runtime.js';
-
-// Re-export RefObject type
-export type {RefObject} from '../engine/hooks-runtime.js';
-
-// Parameter tuning hook
-export {useParam} from '../engine/params-runtime.js';
-export type {ParamDeclaration} from '../engine/params-runtime.js';
+/**
+ * VIBEMANCER - HOOKS API
+ *
+ * Main export file for the hooks-based bot API.
+ */
+
+// Types
+export type {
+	EnemyState,
+	AnalyzedThreat,
+	FinalAction,
+	ActionBuilder,
+	WizardFunction,
+	WizardContext,
+	MissileConfig,
+	MissileContext,
+	MissileAction,
+	MissileFunction,
+} from './types.js';
+
+// State hooks
+export {
+	useRandom,
+	useHealth,
+	usePosition,
+	useVelocity,
+	useStatus,
+	useTicksUntilReady,
+	useShieldStrength,
+	useBlinkCooldown,
+	useCastingSpell,
+	useCastProgress,
+	useEnemy,
+	useProjectiles,
+	useMyProjectiles,
+	useLastMissileConfig,
+	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,
+	aim,
+	blink,
+	cancel,
+	move,
+	idle,
+	extractAction,
+	turnToward,
+	turnToAngle,
+	flyStraight,
+	extractMissileAction,
+} from './action-builders.js';
+
+// Re-export persistence hooks from runtime
+export {
+	useState,
+	useEffect,
+	useMemo,
+	useRef,
+	runWizardWithContext,
+	withWizardContext,
+	withMissileContext,
+	getWizardContext,
+	getMissileContext,
+} from '../engine/hooks-runtime.js';
+
+// Re-export RefObject type
+export type {RefObject} from '../engine/hooks-runtime.js';
+
+// Parameter tuning hook
+export {useParam} from '../engine/params-runtime.js';
+export type {ParamDeclaration} from '../engine/params-runtime.js';

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};