@vibemancer/core 1.0.9 → 1.0.11

package/src/hooks/threat-analysis.ts

@@ -119,6 +119,7 @@ function analyzeOneThreat(
 			canDodgeLeft,
 			canDodgeRight,
 			canOutrun,
+			ticksToImpact,
 		);
 	}
 
@@ -244,12 +245,14 @@ function simulateDodge(
 		// Stryker disable next-line ArithmeticOperator: same as above
 		const newY = targetPos.y + dodgeDir.y * RULES.MOVEMENT_SPEED;
 
-		// Stryker disable all: arena clamp sign — +/- COLLISION_RADIUS equivalent (wizard rarely reaches exact wall boundary during dodge)
+		// Clamped to the survivable band, which models "dodge as far as you safely can" —
+		// the wizard stops at the lava rather than walking into it. Feasibility is judged on
+		// that basis; whether the ADVICE points at the lava is decided in
+		// calculateBestDodgeDirection, which is where the real defect was.
 		targetPos = {
 			x: Math.max(ARENA_MIN + COLLISION_RADIUS, Math.min(ARENA_MAX - COLLISION_RADIUS, newX)),
 			y: Math.max(ARENA_MIN + COLLISION_RADIUS, Math.min(ARENA_MAX - COLLISION_RADIUS, newY)),
 		};
-		// Stryker restore all
 
 		// Stryker disable next-line ConditionalExpression,EqualityOperator: turnRate>=0 equivalent (homing with rate 0 is no-op)
 		if (turnRate > 0)
@@ -341,35 +344,71 @@ function getDodgeDirection(
 /**
  * Calculate the best dodge direction based on available options.
  */
+/**
+ * How far a wizard can travel from `from` along `dir` before its edge touches lava.
+ *
+ * Used only to break a tie between two dodges that both work. Larger is better: it is the
+ * margin the bot has if it keeps moving, which is what bots actually do.
+ */
+function roomBeforeLava(from: Position, dir: Position): number
+{
+	const min = ARENA_MIN + COLLISION_RADIUS;
+	const max = ARENA_MAX - COLLISION_RADIUS;
+	const along = (pos: number, d: number, lo: number, hi: number): number =>
+	{
+		// A component that is effectively zero means this axis never runs out — not that it
+		// runs out immediately. Comparing against exact zero was not enough: standing on the
+		// boundary, a direction of (1, -1.8e-16) gave (35 - 35) / -1.8e-16 = 0, so the SAFE
+		// direction scored no room and lost to the lava-ward one. And standing exactly on the
+		// boundary is precisely what clampToSafeZone hands back.
+		if (Math.abs(d) < 1e-9) return Number.POSITIVE_INFINITY;
+		return d > 0 ? (hi - pos) / d : (lo - pos) / d;
+	};
+	// The binding axis is whichever runs out first.
+	return Math.max(0, Math.min(along(from.x, dir.x, min, max), along(from.y, dir.y, min, max)));
+}
+
 function calculateBestDodgeDirection(
 	projectile: ProjectileState,
 	targetPos: Position,
 	canDodgeLeft: boolean,
 	canDodgeRight: boolean,
 	canOutrun: boolean,
+	ticksToImpact: number,
 ): Position | null
 {
-	// Stryker disable next-line ConditionalExpression: replacing with false just falls through to the `else if (canDodgeLeft)` which returns the same value
-	if (canDodgeLeft && canDodgeRight)
-	{
-		// Both sides work - pick the one closer to where we want to be
-		// For simplicity, just return left
-		return getDodgeDirection(projectile, targetPos, 'left');
-	}
-	else if (canDodgeLeft)
+	// Every feasible candidate is checked for whether you SURVIVE it, not just the two-sided
+	// case. The first version of this fix guarded only `canDodgeLeft && canDodgeRight`, so
+	// when one side was feasible it was returned unchecked — and simulateDodge clamps the
+	// wizard at the band edge, so it calls a dodge feasible when following it walks into the
+	// lava. A sweep of 38,280 suggestions found 114 still doing that.
+	// A dodge is only worth recommending if the wizard is still alive at impact.
+	const travel = RULES.MOVEMENT_SPEED * Math.max(1, Math.min(ticksToImpact, 600));
+	const survives = (dir: Position): boolean => roomBeforeLava(targetPos, dir) >= travel;
+
+	// Sidesteps first, outrunning last — a sidestep leaves the missile's path while outrunning
+	// merely delays it, and that ordering predates the lava work. Room only breaks the tie
+	// BETWEEN the two sidesteps.
+	const sides: Position[] = [];
+	if (canDodgeLeft) sides.push(getDodgeDirection(projectile, targetPos, 'left'));
+	if (canDodgeRight) sides.push(getDodgeDirection(projectile, targetPos, 'right'));
+
+	const safeSides = sides.filter(survives);
+	if (safeSides.length > 0)
 	{
-		return getDodgeDirection(projectile, targetPos, 'left');
+		return safeSides.reduce((best, dir) =>
+			(roomBeforeLava(targetPos, dir) > roomBeforeLava(targetPos, best) ? dir : best));
 	}
-	else if (canDodgeRight)
-	{
-		return getDodgeDirection(projectile, targetPos, 'right');
-	}
-	else if (canOutrun)
+
+	if (canOutrun)
 	{
-		return getDodgeDirection(projectile, targetPos, 'away');
+		const away = getDodgeDirection(projectile, targetPos, 'away');
+		if (survives(away)) return away;
 	}
 
-	// No dodge available
+	// Nothing survivable. Saying so is the honest answer: a caller reading null shields or
+	// blinks instead, which is the right response to "there is nowhere to go". Naming a
+	// direction that kills you is not a dodge.
 	return null;
 }
 

package/src/hooks/types.ts

@@ -22,7 +22,8 @@ import {Position, Velocity, ProjectileState, MissileConfig, WizardActions, GameS
  */
 export interface EnemyState
 {
-	/** Enemy position in world coordinates (0-800). */
+	/** Enemy position in world coordinates. The arena is 0-860; the survivable playfield is
+	 *  [30, 830], and outside that band is lava. */
 	position: Position;
 	/** Enemy velocity in units/tick. */
 	velocity: Velocity;
@@ -108,9 +109,20 @@ export interface ActionBuilder extends FinalAction
 	 * 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.
+	 * `lockAim()` holds your angle for the whole cast — but it is USUALLY THE WRONG TOOL for
+	 * leading, and this comment used to claim the opposite. Measured over 1,140 matches
+	 * against the built-ins: auto-aim wins 80.5%, lockAim with a computed lead wins 29.3%,
+	 * and it degrades monotonically the more shots you lock.
+	 *
+	 * The reason is cast time. A cast runs 88-240 ticks — up to 2.4 SECONDS — and lockAim
+	 * freezes the angle at cast START, so it is stale long before the missile leaves. No bot
+	 * holds a heading that long.
+	 *
+	 * TO LEAD A TARGET, call `aim(degrees)` on every tick of the cast and recompute the lead
+	 * each time: same harness, 85.4%. That is what makes `getLeadPosition` worth calling.
+	 *
+	 * lockAim is for aiming at a PLACE rather than a bot — a lava edge, an escape lane, an
+	 * area you want denied — where a fixed angle is the point.
 	 *
 	 * Chainable — `missile(cfg, ai, angle).lockAim().move(0, 1)` aims, fires and kites.
 	 */

package/src/rules.ts

@@ -199,6 +199,14 @@ export function validateMissileConfig(config: MissileConfig): MissileConfig
  * If lastMissileConfig is a MissileConfig, applies warmup multiplier:
  * - Similar to previous: up to 20% faster
  * - Very different: up to 20% slower (switching penalty)
+ *
+ * @returns cast time in SECONDS — multiply by TICKS_PER_SECOND for ticks.
+ *
+ * Bot authors almost always want `getMissileCastTime` from utils/combat.ts instead, which
+ * has the identical signature and returns TICKS, the unit the guide and every other number in
+ * the API use. Both are exported and both appear in vibemancer_api as `(config, last?) =>
+ * number`, so the unit was impossible to tell apart: 2.747 read as three ticks rather than
+ * 275.
  */
 export function calculateMissileCastTime(config: MissileConfig, lastMissileConfig: MissileConfig | undefined | null = null): number
 {

package/src/types.ts

@@ -113,17 +113,21 @@ export interface GameState
  * Actions returned by wizard each tick.
  *
  * Movement uses world-space coordinates:
- * - x: +100 = right, -100 = left
- * - y: +100 = down, -100 = up
- * - Diagonal movement is normalized (magnitude capped at 100)
+ * - x: positive = right, negative = left
+ * - y: positive = down, negative = up
+ * - Only the DIRECTION matters: the vector is normalised, and magnitude is capped at 1.
+ *   move(1, 0), move(5, 0) and move(100, 0) are identical; move(0.5, 0) is half speed.
  * - No rotation tracking - just output (x, y) direction
+ *
+ * The old wording here described a [-100, 100] scale, which has not been true for a long
+ * time and is 100x off.
  */
 export interface WizardActions
 {
 	/**
-	 * Movement direction in world-space.
-	 * Values are clamped to [-100, 100] range.
-	 * Magnitude is normalized to max 100 for diagonal movement.
+	 * Movement direction in world-space. Only the direction matters — the vector is
+	 * normalised and its magnitude is capped at 1, so move(100, 0) and move(1, 0) are the
+	 * same full-speed step. A magnitude below 1 moves proportionally slower.
 	 */
 	move: {
 		x: number;