@vibemancer/core 1.0.10 → 1.0.11

package/src/engine/simulation.ts

@@ -32,6 +32,7 @@ import {runWithHooks, resetAllHooks, clearHooks} from './hooks-runtime.js';
 import {angleTo, normalizeAngle, angleDiff} from '../utils/angles.js';
 import {createBudgetState, createFightBudget, recordSpend, mayAct, type BotBudgetState, type BudgetLimits, type FightBudget} from './bot-compute-budget.js';
 import {createRandom, createEntitySeed} from '../utils/random.js';
+import {describeThrown, cappedNotice, MAX_ERRORS_PER_MATCH} from './bot-error-capture.js';
 
 export interface InternalWizardState extends WizardState
 {
@@ -175,11 +176,14 @@ export function tick(
 	projectiles: ProjectileState[];
 	events: SimEvent[];
 	errors: BotError[];
+	budgetExhausted: BudgetExhaustion[];
 	budgets?: [BotBudgetState, BotBudgetState];
 }
 {
 	const nextTick = currentTick + 1;
 	const errors: BotError[] = [];
+	const budgetExhausted: BudgetExhaustion[] = [];
+
 	const events: SimEvent[] = [];
 
 	// 1. Run wizard AIs with isolated random generators
@@ -215,7 +219,17 @@ export function tick(
 		const state = nextBudgets?.[index];
 
 		// An exhausted bot is not called at all, so its remaining ticks are free.
-		if (state && !mayAct(state)) return IDLE_ACTION();
+		if (state && !mayAct(state))
+		{
+			// Reported once, on the tick it is first refused. The bot is skipped for thousands
+			// of ticks afterwards, and thousands of identical records is not a report.
+			if (!state.reported)
+			{
+				state.reported = true;
+				budgetExhausted.push({tick: nextTick, entityId, spentMs: state.spentMs});
+			}
+			return IDLE_ACTION();
+		}
 
 		const startedAt = state ? Date.now() : 0;
 		let action: WizardActions;
@@ -225,7 +239,13 @@ export function tick(
 		}
 		catch(e)
 		{
-			errors.push({tick: nextTick, entityId, message: e instanceof Error ? e.message : String(e)});
+			const alreadyDead = (wizards[index]?.health ?? 1) <= 0;
+			errors.push({
+				tick: nextTick,
+				entityId,
+				message: describeThrown(e),
+				...(alreadyDead ? {afterDeath: true} : {}),
+			});
 			action = IDLE_ACTION();
 		}
 
@@ -356,12 +376,24 @@ export function tick(
 				}
 				else if (spell === 'blink' && wizard.blinkTarget)
 				{
-					// Clamp blink target to RULES.BLINK_RANGE from current position
-					const dx = wizard.blinkTarget.x - wizard.position.x;
-					const dy = wizard.blinkTarget.y - wizard.position.y;
+					// A bot's coordinates are untrusted input, exactly like its move vector.
+					//
+					// blink(NaN, NaN) used to make the wizard's position NaN — isInLava reads
+					// that as false so nobody dies, and resolveWizardCollision then divided by
+					// a NaN distance and wrote NaN into the OPPONENT's position too. Both
+					// wizards froze and every match was a silent draw. calculateBlinkCooldown
+					// went NaN with it, and `NaN > 0` is false, so the cooldown gate stopped
+					// working as well.
+					//
+					// moveWizard was hardened for this and blink was not, so the same one-line
+					// exploit just moved to the other door. A non-finite target blinks NOWHERE.
+					const targetX = Number.isFinite(wizard.blinkTarget.x) ? wizard.blinkTarget.x : wizard.position.x;
+					const targetY = Number.isFinite(wizard.blinkTarget.y) ? wizard.blinkTarget.y : wizard.position.y;
+					const dx = targetX - wizard.position.x;
+					const dy = targetY - wizard.position.y;
 					const distance = Math.sqrt(dx * dx + dy * dy);
 
-					let targetPos = wizard.blinkTarget;
+					let targetPos = {x: targetX, y: targetY};
 					if (distance > RULES.BLINK_RANGE)
 					{
 						// Clamp to max range in the same direction
@@ -558,7 +590,7 @@ export function tick(
 				}
 				catch(e)
 				{
-					errors.push({tick: nextTick, entityId: projectile.id, message: e instanceof Error ? e.message : String(e)});
+					errors.push({tick: nextTick, entityId: projectile.id, message: describeThrown(e)});
 				}
 
 				targetAngle = missileActions.turnToward
@@ -569,7 +601,13 @@ export function tick(
 			}
 		} // end else (not guided)
 
-		if (targetAngle !== null)
+		// A missile AI's steering is untrusted input too. `turnToward(NaN, NaN)` sent a NaN
+		// angle into angleDiff, so the projectile's rotation and position went NaN and it
+		// could never hit anything — and nothing was reported, because returning nonsense is
+		// not throwing. A bot doing this LOST silently; the same bot throwing got a full
+		// report. Ignoring the instruction means the missile flies straight, which is what a
+		// missile with no steering does.
+		if (targetAngle !== null && Number.isFinite(targetAngle))
 		{
 			const diff = angleDiff(projectile.rotation, targetAngle);
 			const turn = Math.max(-projectile.turnRate, Math.min(projectile.turnRate, diff));
@@ -668,6 +706,7 @@ export function tick(
 		projectiles: remainingProjectiles,
 		events,
 		errors,
+		budgetExhausted,
 		budgets: nextBudgets,
 	};
 }
@@ -851,11 +890,44 @@ export type FightWinner = 'wizard-1' | 'wizard-2' | 'draw';
  * Result of a simulation.
  */
 /** A runtime error captured from a bot or missile AI function. */
+/**
+ * A bot that ran out of its compute budget and stopped being called.
+ *
+ * Deliberately NOT a BotError. Errors feed `consecutiveCrashes` on the ladder and
+ * auto-deactivate a wizard at three; being slow on a loaded server must never cost someone
+ * their bot. But it was recorded NOWHERE, so a bot that burned its allowance stood still for
+ * the rest of the fight and reported a clean scoreline — measured, a certain 10-0 became 1
+ * win and 9 draws with nothing saying why.
+ */
+export interface BudgetExhaustion
+{
+	entityId: string;
+	/** The tick the bot was first refused. */
+	tick: number;
+	/** How much it had spent when it was cut off, in milliseconds. */
+	spentMs: number;
+	/** 1-based match index within a fight; set by `fight()`, absent from a lone simulate(). */
+	match?: number;
+}
+
 export interface BotError
 {
 	tick: number;
 	entityId: string;
 	message: string;
+	/**
+	 * True when the wizard was ALREADY DEAD on the tick this was thrown.
+	 *
+	 * The engine keeps calling a bot after its health reaches zero and discards the action, so
+	 * these errors change nothing. Unmarked they are actively misleading in two ways: a player
+	 * sees a fault spanning hundreds of ticks with no hint the wizard was dead for all of
+	 * them, and the ladder counts them toward consecutiveCrashes — so a bot can be
+	 * auto-deactivated for errors the guide itself calls harmless.
+	 *
+	 * The engine is the only place that knows, so it is recorded here rather than guessed
+	 * downstream from a reconstructed death tick.
+	 */
+	afterDeath?: boolean;
 	/**
 	 * 1-based index within the fight's TEN matches, present only on `FightResult.allErrors`.
 	 *
@@ -876,6 +948,15 @@ export interface SimulateResult
 	history: GameState[];
 	/** Runtime errors thrown by bot or missile AI functions (empty if no errors). */
 	errors: BotError[];
+	/**
+	 * Bots that ran out of compute and stopped being called (empty if nobody did).
+	 *
+	 * Separate from `errors` on purpose: errors feed consecutiveCrashes and deactivate a
+	 * wizard at three, and being slow must never do that. But it has to be reported SOMEWHERE
+	 * — a bot cut off in match 1 stands still for the rest of the fight, and without this the
+	 * player sees a clean scoreline and rewrites a strategy that was never the problem.
+	 */
+	budgetExhausted: BudgetExhaustion[];
 }
 
 /**
@@ -906,6 +987,14 @@ export interface FightResult
 	 * raw would blame each side's faults on the other.
 	 */
 	allErrors: BotError[];
+	/**
+	 * Bots cut off by the compute budget, across all ten matches.
+	 *
+	 * The budget is FIGHT-scoped, so this is where it belongs: exhausting it in match 1
+	 * freezes the bot for the other nine. Ids are in the caller's frame, mirrored out of the
+	 * swapped matches like allErrors.
+	 */
+	budgetExhausted: BudgetExhaustion[];
 }
 
 /**
@@ -956,6 +1045,7 @@ export function fight(
 {
 	const matches: SimulateResult[] = [];
 	const allErrors: BotError[] = [];
+	const allBudgetExhausted: BudgetExhaustion[] = [];
 	// 1..10 in the order matches are played, so the number a player is shown is the number
 	// every tool description promises.
 	let matchNumber = 1;
@@ -978,6 +1068,7 @@ export function fight(
 
 		matches.push(result);
 		allErrors.push(...result.errors.map((e) => ({...e, match: matchNumber})));
+		allBudgetExhausted.push(...result.budgetExhausted.map((b) => ({...b, match: matchNumber})));
 		matchNumber++;
 
 		if (result.winner === 'wizard-1')
@@ -1021,6 +1112,7 @@ export function fight(
 		// into the caller's frame first: this match ran bot 2 as "wizard-1", so passing the
 		// records through raw would report each bot's faults against the other.
 		allErrors.push(...swapped.errors.map((e) => ({...e, entityId: swapSide(e.entityId), match: matchNumber})));
+		allBudgetExhausted.push(...swapped.budgetExhausted.map((b) => ({...b, entityId: swapSide(b.entityId), match: matchNumber})));
 		matchNumber++;
 
 		// Don't push swapped match to matches array (it's only for scoring)
@@ -1043,7 +1135,7 @@ export function fight(
 		: wizard2Wins > wizard1Wins ? 'wizard-2'
 			: 'draw';
 
-	return {wizard1Wins, wizard2Wins, draws, winner, matches, allErrors};
+	return {wizard1Wins, wizard2Wins, draws, winner, matches, allErrors, budgetExhausted: allBudgetExhausted};
 }
 
 /**
@@ -1145,6 +1237,7 @@ export function simulate(
 	let projectiles: ProjectileState[] = [];
 	const missileAIs = new Map<string, MissileFunction>();
 	const allErrors: BotError[] = [];
+	const allBudgetExhausted: BudgetExhaustion[] = [];
 
 	let deathTick: number | null = null;
 
@@ -1171,7 +1264,23 @@ export function simulate(
 		currentTick = result.nextTick;
 		wizards = result.wizards;
 		projectiles = result.projectiles;
-		if (result.errors.length > 0) allErrors.push(...result.errors);
+		// Bounded on purpose. This array lives for the whole match, so leaving it unbounded
+		// lets a bot choose how much memory the engine allocates — and a ~2KB message thrown
+		// every tick genuinely exhausts the isolate, after which the failure surfaces as an
+		// infrastructure fault and, on the ladder, is blamed on nobody or on the opponent.
+		for (const error of result.errors)
+		{
+			if (allErrors.length > MAX_ERRORS_PER_MATCH) break;
+			if (allErrors.length === MAX_ERRORS_PER_MATCH)
+			{
+				// Announce the cap; going quiet here would recreate the silent failure that
+				// surfacing bot errors existed to fix.
+				allErrors.push(cappedNotice(error.entityId, error.tick));
+				break;
+			}
+			allErrors.push(error);
+		}
+		if (result.budgetExhausted.length > 0) allBudgetExhausted.push(...result.budgetExhausted);
 
 		if (!skipHistory)
 		{
@@ -1216,5 +1325,6 @@ export function simulate(
 		finalState,
 		history: skipHistory ? [] : history,
 		errors: allErrors,
+		budgetExhausted: allBudgetExhausted,
 	};
 }

package/src/engine-version.ts

@@ -9,7 +9,7 @@
  * Used to gate spectator replays: a recorded match can only be re-simulated when
  * the runtime engine version matches the version that produced the match.
  */
-export const ENGINE_VERSION = 293192982913104;
+export const ENGINE_VERSION = 2983169471988242;
 
 /**
  * Historical versions that denote the SAME engine as `ENGINE_VERSION`.

package/src/hooks/action-builders.ts

@@ -90,7 +90,7 @@ export function shield(): ActionBuilder
  * 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
+ * take longer to cast. While casting you move at 33% speed. After firing, 100-tick
  * (1s) GCD before next spell.
  *
  * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
@@ -158,13 +158,16 @@ export function aim(degrees: number): ActionBuilder
  *
  * 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)
+ *   - 10 units → 100 ticks (1s); 100 units → 667 ticks; 150 → 1000 (10s); 300 → 2000 (20s).
+ *     The cooldown scales with DISTANCE — a micro-blink costs a second, a full-range one
+ *     costs twenty. This line used to claim 100 units → 100 ticks, understating it 6.7x.
  *   - 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)
+ * @param x - Target X position (absolute world coordinate; arena is 0-860, and the
+ *            survivable playfield is [30, 830] — outside that band is lava)
+ * @param y - Target Y position (absolute world coordinate; see x)
  *
  * @example
  *   return blink(400, 400);                              // blink to center
@@ -295,5 +298,109 @@ export function extractMissileAction(action: MissileAction): MissileActions
  */
 export function extractAction(finalAction: FinalAction): WizardActions
 {
-	return finalAction._toAction();
+	// Checked rather than assumed, because the failure message is what a player debugs from.
+	//
+	// This used to be a bare `finalAction._toAction()`, so returning undefined gave "Cannot
+	// read properties of undefined (reading '_toAction')" and returning a plain object gave
+	// "finalAction._toAction is not a function". `_toAction` is internal and appears nowhere
+	// in the player-facing API, so the message named the one thing they cannot look up.
+	//
+	// Returning `{move: {x: 1, y: 0}}` is the most common version of this mistake — it is
+	// exactly the shape of WizardActions — which made the likeliest error the least useful.
+	if (finalAction === null || finalAction === undefined || typeof finalAction._toAction !== 'function')
+	{
+		// Named specifically rather than by bare typeof: "a object" is both ungrammatical and
+		// unhelpful, and the realistic version of this mistake is `async function MyBot()`,
+		// where the value is a Promise and the fix is to remove the `async`.
+		const describeReturned = (value: unknown): string =>
+		{
+			if (value === null) return 'null';
+			if (value === undefined) return 'undefined';
+			if (Array.isArray(value)) return 'an array';
+			if (typeof value === 'object')
+			{
+				if ('then' in value && typeof value.then === 'function')
+				{
+					return 'a Promise — your bot function is `async`, and it must not be: remove the async keyword';
+				}
+				return 'a plain object';
+			}
+			return `a ${typeof value}`;
+		};
+		const got = describeReturned(finalAction);
+		throw new Error(
+			`Your bot returned ${got}. Return one of: idle(), move(x, y), missile(config, ai, angle), `
+			+ 'shield(), blink(x, y), cancel() or aim(degrees). '
+			+ 'A bot must return an action every tick — returning nothing throws, it does not skip the tick.',
+		);
+	}
+	// Read every number the engine will later use, HERE — inside the bot's own try/catch.
+	//
+	// A bot can hand back an object with a throwing `valueOf`, and the engine reads those
+	// coordinates later, outside runBot's try/catch: `wizard.blinkTarget.x - position.x` at
+	// blink completion. The throw then escaped tick -> simulate -> fight and surfaced as a
+	// bare fight failure with NO bot named. Two things followed, both serious:
+	//
+	//   - the ladder blamed whichever wizard happened to be PICKED, giving an innocent bot a
+	//     loss, a lastError and a crash strike toward deactivation;
+	//   - the message was forgeable. `throw new Error('Script execution timed out')` from a
+	//     valueOf never passes through the harness, so it matched the INFRASTRUCTURE markers
+	//     and the ladder SKIPPED the match — an unlosable bot — while the fight tool printed a
+	//     confident explanation about infinite loops for a bot containing no loop.
+	//
+	// Forcing the conversion now means a hostile valueOf throws where every other bot fault
+	// throws: inside the try, attributed to the bot that wrote it.
+	const action = finalAction._toAction();
+
+	// The shape was checked and the RESULT was trusted. `{_toAction: () => 'junk'}` therefore
+	// passed straight through: ten draws, zero errors, nothing reported — the same silent
+	// failure this area exists to remove, one level further in. An action without a `move` is
+	// not an action, whatever produced it.
+	if (action === null || typeof action !== 'object' || typeof (action as WizardActions).move !== 'object'
+		|| (action as WizardActions).move === null)
+	{
+		throw new Error(
+			'Your bot returned something that is not a valid action. Build actions with the provided '
+			+ 'functions — idle(), move(x, y), missile(config, ai, angle), shield(), blink(x, y), '
+			+ 'cancel() or aim(degrees) — rather than constructing the object yourself.',
+		);
+	}
+
+	return normaliseActionNumbers(action);
+}
+
+/**
+ * Coerce an action's numeric fields eagerly, so lazy getters cannot fire inside the engine.
+ *
+ * Deliberately NOT a validation pass — invalid values are still handled where they always
+ * were (moveWizard, the blink guard, validateMissileConfig). This only decides WHEN the
+ * numbers are read, and therefore who gets blamed when reading one throws.
+ */
+function normaliseActionNumbers(action: WizardActions): WizardActions
+{
+	const num = (value: unknown): number => Number(value);
+
+	const normalised: WizardActions = {
+		...action,
+		move: {x: num(action.move?.x), y: num(action.move?.y)},
+	};
+
+	if (action.aimDirection !== undefined) normalised.aimDirection = num(action.aimDirection);
+
+	if (action.startCast?.spell === 'missile')
+	{
+		normalised.startCast = {
+			...action.startCast,
+			...(action.startCast.direction !== undefined ? {direction: num(action.startCast.direction)} : {}),
+		};
+	}
+	else if (action.startCast?.spell === 'blink')
+	{
+		normalised.startCast = {
+			...action.startCast,
+			target: {x: num(action.startCast.target?.x), y: num(action.startCast.target?.y)},
+		};
+	}
+
+	return normalised;
 }