@vibemancer/core 1.0.10 → 1.0.12

package/src/hooks/threat-analysis.ts

@@ -19,6 +19,14 @@ import {distanceTo} from '../utils/distance.js';
 import {angleTo, normalizeAngle, angleDiff} from '../utils/angles.js';
 import type {AnalyzedThreat} from './types.js';
 
+/**
+ * Ticks lost to cancel() before a new cast can begin.
+ *
+ * The guide states it: cancel() "returns you to idle immediately and costs NO cooldown, but
+ * it takes effect after this tick's cast check — so you can shield on the NEXT tick".
+ */
+const CANCEL_COST_TICKS = 1;
+
 // Maximum distance at which a missile is still tracked as a potential threat
 // (even if simulation says it will miss — homing missiles can change course)
 const THREAT_RELEVANCE_DISTANCE = 500;
@@ -30,6 +38,9 @@ const THREAT_RELEVANCE_DISTANCE = 500;
  * @param projectiles - All projectiles in the game
  * @param myProjectiles - Only the bot's own projectiles (used for filtering)
  * @param ticksUntilReady - Ticks until wizard can start a new action
+ * @param options - `canCancelCurrentCast` when the wizard is mid-CAST and could cancel()
+ *                  out of it for one tick's cost. Defaults to false, which is the safe
+ *                  reading for a caller that does not know its own state.
  * @returns Array of analyzed threats sorted by ticksToImpact (soonest first)
  */
 export function analyzeThreats(
@@ -37,6 +48,7 @@ export function analyzeThreats(
 	projectiles: ProjectileState[],
 	myProjectiles: ProjectileState[],
 	ticksUntilReady: number,
+	options?: {canCancelCurrentCast?: boolean},
 ): AnalyzedThreat[]
 {
 	// Filter to enemy projectiles by excluding our own
@@ -48,7 +60,7 @@ export function analyzeThreats(
 
 	for (const projectile of enemyProjectiles)
 	{
-		const analysis = analyzeOneThreat(myPos, projectile, ticksUntilReady);
+		const analysis = analyzeOneThreat(myPos, projectile, ticksUntilReady, options?.canCancelCurrentCast ?? false);
 		// Only include if it will hit or missile is within reasonable distance
 		const missileDistance = Math.sqrt(
 			(projectile.position.x - myPos.x) ** 2 +
@@ -74,6 +86,7 @@ function analyzeOneThreat(
 	targetPos: Position,
 	projectile: ProjectileState,
 	ticksUntilReady: number,
+	canCancelCurrentCast: boolean,
 ): AnalyzedThreat
 {
 	// Ask the ENGINE for the collision radius rather than re-deriving it.
@@ -119,16 +132,26 @@ function analyzeOneThreat(
 			canDodgeLeft,
 			canDodgeRight,
 			canOutrun,
+			ticksToImpact,
 		);
 	}
 
-	// Calculate shield timing
-	// Can block if: ticksUntilReady + shield cast time < ticksToImpact
-	// Stryker disable next-line EqualityOperator,ArithmeticOperator: ±1 tick boundary is intentional buffer, not precisely testable
-	const canBlockInTime = ticksToImpact > ticksUntilReady + RULES.SHIELD_CAST_TIME + 1;
+	// Shield timing. These two fields MUST be satisfiable together: a bot acts on
+	// `canBlockInTime && ticksToStartShield === 0`, so if they can never both hold the bot
+	// never shields. They used to disagree — canBlockInTime charged the wizard the whole
+	// remainder of its cast while ticksToStartShield ignored the cast entirely — and mid-cast
+	// that made them mutually exclusive. Measured cost: zero shields raised in a full match.
+	//
+	// The pessimism was wrong as well as inconsistent. cancel() leaves a CAST for one tick's
+	// cost, so a casting wizard's real delay is 1, not the couple of hundred ticks remaining.
+	// A GCD is different: nothing can be started during it and it cannot be cancelled, so
+	// there the full ticksUntilReady genuinely does apply.
+	const delayBeforeShield = canCancelCurrentCast ? CANCEL_COST_TICKS : ticksUntilReady;
 
-	// When to start casting shield (leave 1 tick buffer)
-	const ticksToStartShield = Math.max(0, ticksToImpact - RULES.SHIELD_CAST_TIME - 1);
+	// One tick of slack, so the window is not a single exact frame.
+	const ticksNeededToBlock = delayBeforeShield + RULES.SHIELD_CAST_TIME + 1;
+	const canBlockInTime = ticksToImpact >= ticksNeededToBlock;
+	const ticksToStartShield = Math.max(0, ticksToImpact - ticksNeededToBlock);
 
 	return {
 		id: projectile.id,
@@ -244,12 +267,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 +366,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)
+	// 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)
 	{
-		// Both sides work - pick the one closer to where we want to be
-		// For simplicity, just return left
-		return getDodgeDirection(projectile, targetPos, 'left');
+		return safeSides.reduce((best, dir) =>
+			(roomBeforeLava(targetPos, dir) > roomBeforeLava(targetPos, best) ? dir : best));
 	}
-	else if (canDodgeLeft)
-	{
-		return getDodgeDirection(projectile, targetPos, 'left');
-	}
-	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;

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

@@ -44,6 +44,7 @@ export interface WizardState
 	lastMissileConfig?: MissileConfig; // last fired missile (for warmup system)
 	warmupMultiplier?: number; // warmup multiplier applied to most recent missile cast (0.80 = full bonus, 1.20 = full penalty)
 	invincible?: boolean; // manual play mode: damage is ignored when true
+	advised?: {nonFinite?: boolean; unfinishableCast?: boolean}; // engine advisories already given, so each is reported once per match
 }
 
 /**
@@ -113,17 +114,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;