azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/bg/avEnemyPush.ts

@@ -0,0 +1,219 @@
+/**
+ * The other side's push, simulated as ONE agent instead of forty bodies.
+ *
+ * Operator direction (2026-09-01): "there must be an enemy team doing pve tactics as in running to
+ * balinda and galv and clearing their way down the lieutenant bosses, and towers etc until they
+ * reach base where they capture it and start boss themselves. preferably coded smart where its
+ * same fog of war and we dont need to do all their calculations if we dont see them."
+ *
+ * So this is deliberately NOT a second raid of live bodies. It is a cursor walking the mirror of
+ * your own objective list — their captain, their four tower garrisons, their general — on a clock.
+ * The valley is 2,800 yards; you cannot see their push from yours, and a body you never see costs
+ * nothing to be right about. What you DO see is the consequence, which is the half that matters:
+ *
+ *   - they take one of your towers   -> you lose 75 reinforcements   (BattleGroundAV.h:62)
+ *   - they kill your captain         -> you lose 100                 (BattleGroundAV.h:57)
+ *   - they reach and kill YOUR general -> you lose the battle        (BattleGroundAV.cpp:57)
+ *
+ * That is what makes the 600/600 a RACE rather than a decoration: their bar falls because you push,
+ * yours falls because they do, and the first general to die ends it.
+ *
+ * PACE, and the MARCH is why nobody stands on your captain at the horn. `elapsedMs` is time since
+ * the horn (the instance surface's own prep is AV_PREP_MS, and it ends before this clock starts):
+ * they walk their gate to the first commander and then commander to commander at BASE_RUN_SPEED
+ * over corridor yards — their gate to Galvangar is 1,455 yd straight, so ~6.5 min before they touch
+ * him — then FIGHT for `AV_CAPTIME_MS` per objective, AV's own node assault clock and one constant
+ * to tune rather than a behaviour tree nobody can see.
+ *
+ * MATERIALISING. `avEnemyVisible` says whether the player is close enough to the cursor to see the
+ * push. A caller that wants real bodies spawns them ONLY then — everywhere else the cursor is the
+ * whole simulation. That is the fog of war, and it is why this is cheap.
+ */
+
+import { AV_CAPTIME_MS, AV_RES_CAPTAIN, AV_RES_TOWER } from './av.ts';
+import { AV_DATA, avNode, type AvTeam } from '../../data/alteracValley.ts';
+import { BASE_RUN_SPEED } from '../nav/speed.ts';
+import { detHypot } from '../../engine/core/detMath.ts';
+
+/** How near the push you must be to see it at all. */
+export const AV_ENEMY_SIGHT_YD = 120;
+
+/** Corridor over straight line, mean 1.94 of the four gate-to-commander legs (routed vs straight
+ *  2 yd samples 963/417, 1249/729, 1695/830, 1917/1132). Cite: src/dev/capabilities/avRoute.mjs. */
+export const AV_PATH_FACTOR = 1.9;
+
+export type AvEnemyObjectiveKind = 'captain' | 'tower' | 'general';
+
+export interface AvEnemyObjective {
+  kind: AvEnemyObjectiveKind;
+  /** Creature entry of the commander they are killing. */
+  entry: number;
+  name: string;
+  x: number;
+  y: number;
+  z: number;
+  /** Reinforcements the defender loses when this falls. */
+  cost: number;
+  /** Where this leg starts — their gate for the first, the last commander after that. */
+  from: { x: number; y: number; z: number };
+  /** Corridor yards walked on this leg. */
+  marchYd: number;
+  /** Time on the road before this fight starts, ms. */
+  marchMs: number;
+}
+
+/** One objective per this many ms of FIGHTING. Cite: AV_CAPTIME_MS, AV's own node assault clock. */
+export const AV_ENEMY_OBJECTIVE_MS = AV_CAPTIME_MS;
+
+/** Corridor yards between two field points, and what walking them costs. */
+function marchOf(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+): { marchYd: number; marchMs: number } {
+  const marchYd = detHypot(to.x - from.x, to.y - from.y) * AV_PATH_FACTOR;
+  return { marchYd, marchMs: (marchYd / BASE_RUN_SPEED) * 1000 };
+}
+
+/**
+ * What the enemy of `team` works through, in order: your captain, your four towers nearest their
+ * gate first, then your general — each leg carrying the walk that reaches it. The mirror of
+ * `commandersOf` in data/dungeons/alterac-valley.ts, read off the same bake.
+ */
+export function avEnemyRoute(team: AvTeam): AvEnemyObjective[] {
+  const c = AV_DATA.commanders;
+  const foe: AvTeam = team === 'alliance' ? 'horde' : 'alliance';
+  const gate = AV_DATA.start[foe] ?? { x: 0, y: 0, z: 0 };
+  const out: AvEnemyObjective[] = [];
+  let from = { x: gate.x, y: gate.y, z: gate.z ?? 0 };
+  const push = (o: Omit<AvEnemyObjective, 'from' | 'marchYd' | 'marchMs'>): void => {
+    out.push({ ...o, from, ...marchOf(from, o) });
+    from = { x: o.x, y: o.y, z: o.z };
+  };
+
+  const captain = c.captain[team];
+  if (captain) {
+    push({
+      kind: 'captain',
+      entry: captain.entry,
+      name: captain.name,
+      x: captain.x,
+      y: captain.y,
+      z: captain.z,
+      cost: AV_RES_CAPTAIN,
+    });
+  }
+  // Your towers, nearest THEIR gate first — the order a push actually meets them.
+  const towers = c.lieutenants
+    .map((l) => ({ l, node: l.node ? avNode(l.node) : undefined }))
+    .filter((r) => r.l.entry != null && r.node != null && r.node.owner === team)
+    .sort((a, b) => detHypot(a.node!.x - gate.x, a.node!.y - gate.y)
+      - detHypot(b.node!.x - gate.x, b.node!.y - gate.y));
+  for (const { l, node } of towers) {
+    push({
+      kind: 'tower',
+      entry: l.entry!,
+      name: l.name ?? node!.name,
+      x: node!.x,
+      y: node!.y,
+      z: node!.z,
+      cost: AV_RES_TOWER,
+    });
+  }
+  const general = c.boss[team];
+  if (general) {
+    push({
+      kind: 'general',
+      entry: general.entry,
+      name: general.name,
+      x: general.x,
+      y: general.y,
+      z: general.z,
+      // The general ending the battle is not a reinforcement cost — it is the end.
+      cost: 0,
+    });
+  }
+  return out;
+}
+
+/** On the road, in the fight, or finished. */
+export type AvEnemyPhase = 'march' | 'fight' | 'done';
+
+export interface AvEnemyState {
+  /** How many objectives they have taken. */
+  taken: number;
+  /** What they are working on now, or null once the general is down. */
+  current: AvEnemyObjective | null;
+  /** Reinforcements this push has cost the defender so far. */
+  costSoFar: number;
+  /** Their general kill — the defender has lost. */
+  generalDown: boolean;
+  /** Fraction of the current FIGHT done, 0..1 — still 0 while they are walking to it. */
+  progress: number;
+  phase: AvEnemyPhase;
+  /** ms left in this phase; 0 once the push is done. */
+  phaseLeftMs: number;
+  /** Where the push is right now, interpolated along the leg it is walking. */
+  at: { x: number; y: number; z: number };
+}
+
+function lerp(
+  a: { x: number; y: number; z: number },
+  b: { x: number; y: number; z: number },
+  f: number,
+): { x: number; y: number; z: number } {
+  return { x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f, z: a.z + (b.z - a.z) * f };
+}
+
+/**
+ * Where the enemy push stands at `elapsedMs`. Pure: the same clock always gives the same board, so
+ * nothing has to be ticked, stored or kept in sync, and a re-mount recomputes it exactly.
+ */
+export function avEnemyStateAt(team: AvTeam, elapsedMs: number): AvEnemyState {
+  const route = avEnemyRoute(team);
+  const first = route[0];
+  if (!first) {
+    const nowhere = { x: 0, y: 0, z: 0 };
+    return {
+      taken: 0, current: null, costSoFar: 0, generalDown: true, progress: 1,
+      phase: 'done', phaseLeftMs: 0, at: nowhere,
+    };
+  }
+  let t = Math.max(0, elapsedMs);
+  let cost = 0;
+  for (let i = 0; i < route.length; i++) {
+    const o = route[i]!;
+    if (t < o.marchMs) {
+      return {
+        taken: i, current: o, costSoFar: cost, generalDown: false, progress: 0,
+        phase: 'march', phaseLeftMs: o.marchMs - t,
+        at: lerp(o.from, o, o.marchMs > 0 ? t / o.marchMs : 1),
+      };
+    }
+    t -= o.marchMs;
+    if (t < AV_ENEMY_OBJECTIVE_MS) {
+      return {
+        taken: i, current: o, costSoFar: cost, generalDown: false,
+        progress: t / AV_ENEMY_OBJECTIVE_MS,
+        phase: 'fight', phaseLeftMs: AV_ENEMY_OBJECTIVE_MS - t,
+        at: { x: o.x, y: o.y, z: o.z },
+      };
+    }
+    t -= AV_ENEMY_OBJECTIVE_MS;
+    cost += o.cost;
+  }
+  const last = route[route.length - 1]!;
+  return {
+    taken: route.length, current: null, costSoFar: cost, generalDown: true, progress: 1,
+    phase: 'done', phaseLeftMs: 0, at: { x: last.x, y: last.y, z: last.z },
+  };
+}
+
+/** Can the player see the push? Only then is a body worth spawning. */
+export function avEnemyVisible(
+  state: AvEnemyState,
+  at: { x: number; y: number },
+  yd = AV_ENEMY_SIGHT_YD,
+): boolean {
+  if (!state.current) return false;
+  return detHypot(state.at.x - at.x, state.at.y - at.y) <= yd;
+}

package/src/domain/bg/avField.ts

@@ -0,0 +1,283 @@
+// The AV field: the creature bodies a battleground event slot spawns and despawns. Cite:
+// BattleGroundAV.cpp:596 SpawnEvent(node, teamIdx * BG_AV_MAX_STATES + state) — every guard,
+// lieutenant and general on map 30 is a `creature` row tagged by `creature_battleground`.
+
+import type { BgPos, BgTeam, BgUnit, BgUnitId } from './types.ts';
+import type { BgWorld } from './bgWorld.ts';
+import type { AvFieldHooks } from './av.ts';
+import { AV_DATA } from '../../data/alteracValley.ts';
+import type { AvSpawnRow } from '../../data/alteracValley.ts';
+import type { FactionTemplateDef } from '../../data/schema.ts';
+import { factionHasNoEnemies } from '../creature/faction.ts';
+import { isScriptAnchorCreature } from '../creature/unitFlags.ts';
+
+/** How far a guard chases before it turns back to its post. Cite: creature_template.leash default. */
+export const AV_GUARD_LEASH_YD = 40;
+/** A general or a captain holds its room and never leaves it. */
+export const AV_COMMANDER_LEASH_YD = 25;
+
+export interface AvBody {
+  name: string;
+  level: number;
+  maxHp: number;
+  /** Player class id when the creature maps to one, else 0 — only drives the chip glyph. */
+  cls: number;
+  /** Yards/second. Cite: creature_template.SpeedRun × BASE_RUN_SPEED. */
+  speedYd: number;
+}
+
+export interface AvFieldOpts {
+  world: BgWorld;
+  /** Which side a creature entry fights for, from `creature_template.FactionAlliance`. */
+  teamOf(entry: number): BgTeam | null;
+  /** Level / health / speed for one creature entry; null drops the body. */
+  bodyOf(entry: number): AvBody | null;
+  onSpawn?(unit: BgUnit): void;
+  onDespawn?(unit: BgUnit): void;
+}
+
+export interface AvField extends AvFieldHooks {
+  /** The always-on half of the map: wildlife, quest givers, base guards, the generals' rooms. */
+  spawnStatic(): void;
+  /**
+   * Put one body on the field with no event slot behind it — what a quest milestone buys
+   * (avQuests.ts AV_WAVES). It marches on the enemy keep rather than holding a post.
+   */
+  spawnWaveBody(entry: number, team: BgTeam, at: BgPos, marchTo: BgPos): BgUnit | null;
+  /** Living bodies of one creature entry. */
+  unitsOfEntry(entry: number): BgUnit[];
+  /** Every NPC body currently on the field. */
+  npcs(): BgUnit[];
+  /** Bodies within `yd` of a point — what a session would have to seat to make a fight real. */
+  near(x: number, y: number, yd: number): BgUnit[];
+  /** Total spawned so far, for the capability rows. */
+  spawnedCount(): number;
+}
+
+const COMMANDER_ENTRIES = new Set<number>(
+  [
+    AV_DATA.commanders.boss.alliance?.entry,
+    AV_DATA.commanders.boss.horde?.entry,
+    AV_DATA.commanders.captain.alliance?.entry,
+    AV_DATA.commanders.captain.horde?.entry,
+    ...AV_DATA.commanders.lieutenants.map((l) => l.entry),
+  ].filter((e): e is number => typeof e === 'number'),
+);
+
+/** Spawn rows grouped by their event slot, so a flip is one map lookup rather than a scan. */
+function indexByEvent(rows: readonly AvSpawnRow[]): Map<number, Map<number, AvSpawnRow[]>> {
+  const out = new Map<number, Map<number, AvSpawnRow[]>>();
+  for (const r of rows) {
+    if (r.event1 == null) continue;
+    let byVariant = out.get(r.event1);
+    if (!byVariant) { byVariant = new Map(); out.set(r.event1, byVariant); }
+    const list = byVariant.get(r.event2 ?? 0);
+    if (list) list.push(r);
+    else byVariant.set(r.event2 ?? 0, [r]);
+  }
+  return out;
+}
+
+/**
+ * Templates that must never get a floor body: a script anchor, or a template at war with nobody.
+ * Without this the 3 PvP credit markers, the 6 wing-commander triggers, the 2 Invisible Stalkers
+ * and the 4 Heralds - 17 of the 1,198 AV spawn rows - fall through `teamOf` as neutral, take a
+ * side from `neutralSideFor` below, and stand in the valley as 1 hp enemies.
+ * Cite: Relations.cpp:365 CanAttack; faction template 35 (enemyMask 0, no enemy factions).
+ */
+export function avNonCombatTemplate(
+  creature: { unitFlags?: number } | null | undefined,
+  ft: FactionTemplateDef | null | undefined,
+): boolean {
+  if (!creature) return true;
+  if (isScriptAnchorCreature(creature)) return true;
+  return !!ft && factionHasNoEnemies(ft);
+}
+
+/**
+ * PRODUCT RULE. The valley's wildlife and the neutral mine crews (troggs, gnolls, harpies, rams)
+ * are hostile to BOTH sides in 1.12, and a two-team world has no way to say that. Each such body
+ * takes the side whose keep is FARTHER from it, so the team living next to a pack has to fight it —
+ * which is how the mine and the armor-scrap farm actually play. Deterministic, so a replay matches.
+ */
+function neutralSideFor(row: AvSpawnRow): BgTeam {
+  const a = AV_DATA.commanders.boss.alliance;
+  const h = AV_DATA.commanders.boss.horde;
+  if (!a || !h) return 'horde';
+  const da = (row.x - a.x) ** 2 + (row.y - a.y) ** 2;
+  const dh = (row.x - h.x) ** 2 + (row.y - h.y) ** 2;
+  return da > dh ? 'alliance' : 'horde';
+}
+
+export function createAvField(o: AvFieldOpts): AvField {
+  const { world } = o;
+  const byEvent = indexByEvent(AV_DATA.spawns);
+  /** Live unit ids per event slot, so a re-spawn despawns exactly what it replaces. */
+  const liveByEvent = new Map<number, BgUnitId[]>();
+  const liveByEntry = new Map<number, Set<BgUnitId>>();
+  const npcIds = new Set<BgUnitId>();
+  let spawned = 0;
+  let seq = 0;
+
+  const remember = (u: BgUnit): void => {
+    npcIds.add(u.id);
+    let set = liveByEntry.get(u.npc!.entry);
+    if (!set) { set = new Set(); liveByEntry.set(u.npc!.entry, set); }
+    set.add(u.id);
+  };
+
+  const forget = (u: BgUnit): void => {
+    npcIds.delete(u.id);
+    liveByEntry.get(u.npc!.entry)?.delete(u.id);
+  };
+
+  function spawnRow(row: AvSpawnRow): BgUnit | null {
+    const team = o.teamOf(row.entry);
+    const body = o.bodyOf(row.entry);
+    if (!body) return null;
+    // A neutral creature still needs a side to fight on. `neutralSideFor` is a PRODUCT RULE — see
+    // its own note; two teams cannot express "hostile to everyone".
+    const side: BgTeam = team ?? neutralSideFor(row);
+    const unit: BgUnit = {
+      id: `n${seq++}`,
+      team: side,
+      name: body.name || row.name,
+      cls: body.cls,
+      level: body.level,
+      pos: { x: row.x, y: row.y },
+      z: row.z,
+      hp: body.maxHp,
+      maxHp: body.maxHp,
+      // A general, captain or tower lieutenant reads as `npc-commander`, which is what the AV
+      // strategy bundle aims a push at (strategies.ts avKillCommander).
+      role: COMMANDER_ENTRIES.has(row.entry) ? 'npc-commander' : 'npc-guard',
+      order: { kind: 'hold' },
+      speedYd: body.speedYd,
+      human: false,
+      npc: {
+        entry: row.entry,
+        // `teamOf` returned nothing, so no faction template claims it: wildlife and mine trash.
+        ...(team == null ? { neutral: true } : {}),
+        ...(row.event1 == null ? {} : { event1: row.event1, event2: row.event2 }),
+        post: { x: row.x, y: row.y },
+        leashYd: COMMANDER_ENTRIES.has(row.entry) ? AV_COMMANDER_LEASH_YD : AV_GUARD_LEASH_YD,
+        // MovementType 1 is MOVEMENT_RANDOM — 312 of the valley's spawn rows carry it, and every
+        // one of them stood frozen. Cite: creature.MovementType/spawndist; ObjectMgr.cpp LoadCreatures.
+        ...(row.movementType === 1 && (row.spawndist ?? 0) > 0
+          ? { wanderYd: row.spawndist }
+          : {}),
+      },
+    };
+    world.addUnit(unit);
+    remember(unit);
+    spawned++;
+    o.onSpawn?.(unit);
+    return unit;
+  }
+
+  function despawnEvent(event1: number): void {
+    const ids = liveByEvent.get(event1);
+    if (!ids) return;
+    for (const id of ids) {
+      const u = world.units.get(id);
+      if (!u) continue;
+      forget(u);
+      world.units.delete(id);
+      o.onDespawn?.(u);
+    }
+    liveByEvent.set(event1, []);
+  }
+
+  return {
+    spawnEvent(event1, variant) {
+      despawnEvent(event1);
+      if (variant == null) return;
+      const rows = byEvent.get(event1)?.get(variant);
+      if (!rows) return;
+      const ids: BgUnitId[] = [];
+      for (const row of rows) {
+        const u = spawnRow(row);
+        if (u) ids.push(u.id);
+      }
+      liveByEvent.set(event1, ids);
+    },
+
+    entryAlive(entry) {
+      const set = liveByEntry.get(entry);
+      if (!set) return false;
+      for (const id of set) {
+        const u = world.units.get(id);
+        if (u && world.alive(u)) return true;
+      }
+      return false;
+    },
+
+    spawnStatic() {
+      for (const row of AV_DATA.spawns) {
+        if (row.event1 != null) continue;
+        spawnRow(row);
+      }
+    },
+
+    spawnWaveBody(entry, team, at, marchTo) {
+      const body = o.bodyOf(entry);
+      if (!body) return null;
+      const unit = {
+        id: `n${seq++}`,
+        team,
+        name: body.name,
+        cls: body.cls,
+        level: body.level,
+        pos: { x: at.x, y: at.y },
+        z: 0,
+        hp: body.maxHp,
+        maxHp: body.maxHp,
+        // A wave is not a guard: it walks the length of the valley, so it holds no post and its
+        // leash is the whole map. Cite: BattleGroundAV.cpp:190 — the C++ never implemented this.
+        role: 'npc-commander' as const,
+        order: { kind: 'attack-move' as const, to: { x: marchTo.x, y: marchTo.y } },
+        speedYd: body.speedYd,
+        human: false,
+        npc: { entry, post: { x: marchTo.x, y: marchTo.y }, leashYd: 4000 },
+      };
+      world.addUnit(unit);
+      remember(unit);
+      spawned++;
+      o.onSpawn?.(unit);
+      return unit;
+    },
+
+    unitsOfEntry(entry) {
+      const out: BgUnit[] = [];
+      for (const id of liveByEntry.get(entry) ?? []) {
+        const u = world.units.get(id);
+        if (u) out.push(u);
+      }
+      return out;
+    },
+
+    npcs() {
+      const out: BgUnit[] = [];
+      for (const id of npcIds) {
+        const u = world.units.get(id);
+        if (u) out.push(u);
+      }
+      return out;
+    },
+
+    near(x, y, yd) {
+      const out: BgUnit[] = [];
+      const r2 = yd * yd;
+      for (const id of npcIds) {
+        const u = world.units.get(id);
+        if (!u || !world.alive(u)) continue;
+        const dx = u.pos.x - x;
+        const dy = u.pos.y - y;
+        if (dx * dx + dy * dy <= r2) out.push(u);
+      }
+      return out;
+    },
+
+    spawnedCount: () => spawned,
+  };
+}

package/src/domain/bg/avInstanceNodes.ts

@@ -0,0 +1,197 @@
+/**
+ * Alterac Valley's nodes and mines, for the instance surface.
+ *
+ * Operator direction (2026-09-01): "all AV things needs to stay, rest shud be exact same as raid".
+ * The reinforcement race already rides the run as a pure read (avInstanceScore). Capture does not:
+ * a node has an OWNER and an assault CLOCK, which is state, so it lives on `InstanceRun` beside the
+ * rest of the floor's progress and is restored on a re-mount like everything else there.
+ *
+ * The rules, all from the same source `av.ts` reads for the battleground screen:
+ *
+ *   - a click starts an assault, 10 s              (AV_CAPTURE_CAST_MS, BattleGroundAV.h)
+ *   - an assault matures to owned after 4 minutes  (AV_CAPTIME_MS, BattleGroundAV.h:296-300)
+ *   - you may assault anything you do not own, and re-take your own assaulted point
+ *     (avClaimIntent — .cpp:687/:645 refuse an assault by the current owner)
+ *   - each mine you hold pays one reinforcement every 45 s  (AV_MINE_TICK_MS, .h:28-29)
+ *
+ * TOWERS ARE NOT HERE. On this surface a tower falls when its garrison dies, and that is already an
+ * encounter — `avInstanceScore` reads it off `defeated` and charges the 75. Modelling tower capture
+ * again would be two owners for one fact, which is the exact mistake that made the old AV screen
+ * jiggle. This module owns the SEVEN graveyards and the TWO mines, and nothing else.
+ */
+
+import type { InstanceRun } from '../../world/instances.ts';
+import { AV_DATA, AV_MINES, AV_NODES, type AvTeam } from '../../data/alteracValley.ts';
+import { AV_CAPTIME_MS, AV_CAPTURE_CAST_MS, AV_MINE_TICK_MS } from './av.ts';
+import { detHypot } from '../../engine/core/detMath.ts';
+
+/** How close you must stand to claim a point. Cite: ObjectDefines.h:25 INTERACTION_DISTANCE is 5 yd
+ *  for a click, but a flag is claimed from its base — av.ts uses the node radius the world does. */
+export const AV_NODE_CLAIM_YD = 12;
+
+export type AvNodeState = 'owned' | 'assaulted';
+
+export interface AvNodeStatus {
+  id: string;
+  name: string;
+  kind: 'graveyard' | 'tower';
+  owner: AvTeam | null;
+  state: AvNodeState;
+  /** Run-clock ms the assault matures on; absent while owned. */
+  maturesAtMs?: number;
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** Persisted shape — kept narrow so a save carries the least that rebuilds the board. */
+export type AvNodeSave = { o: AvTeam | null; s: AvNodeState; m?: number };
+
+/** Graveyards only: towers are encounters (see the header). */
+export function avCaptureNodes(): typeof AV_NODES {
+  return AV_NODES.filter((n) => n.kind === 'graveyard');
+}
+
+/** The board, defaults from the DB where the run has said nothing yet. */
+export function avNodeBoard(run: InstanceRun): AvNodeStatus[] {
+  const saved = run.avNodes ?? {};
+  return avCaptureNodes().map((n) => {
+    const s = saved[n.id];
+    const out: AvNodeStatus = {
+      id: n.id,
+      name: n.name,
+      kind: n.kind,
+      owner: s ? s.o : n.owner,
+      state: s ? s.s : 'owned',
+      x: n.x,
+      y: n.y,
+      z: n.z,
+    };
+    if (s?.m != null) out.maturesAtMs = s.m;
+    return out;
+  });
+}
+
+/**
+ * May `team` claim this node right now? Mirrors av.ts avClaimIntent: never your own controlled
+ * point, and an assaulted point is claimable by anyone but the side that started the assault.
+ */
+export function avClaimable(node: AvNodeStatus, team: AvTeam): boolean {
+  if (node.state === 'owned') return node.owner !== team;
+  return node.owner !== team;
+}
+
+/** Nodes within claim range of a point, closest first. */
+export function avNodesInReach(
+  run: InstanceRun,
+  at: { x: number; y: number },
+  yd = AV_NODE_CLAIM_YD,
+): AvNodeStatus[] {
+  return avNodeBoard(run)
+    .map((n) => ({ n, d: detHypot(n.x - at.x, n.y - at.y) }))
+    .filter((r) => r.d <= yd)
+    .sort((a, b) => a.d - b.d)
+    .map((r) => r.n);
+}
+
+function writeNode(run: InstanceRun, id: string, row: AvNodeSave): void {
+  const next: Record<string, AvNodeSave> = { ...(run.avNodes ?? {}) };
+  next[id] = row;
+  run.avNodes = next;
+}
+
+/**
+ * Start an assault on `id` for `team`. Returns the ms the assault matures on, or null when the
+ * node is not claimable. The 10 s cast is the CALLER's (a cast bar); this records the outcome.
+ */
+export function avBeginAssault(
+  run: InstanceRun,
+  id: string,
+  team: AvTeam,
+  nowMs: number,
+): number | null {
+  const node = avNodeBoard(run).find((n) => n.id === id);
+  if (!node || !avClaimable(node, team)) return null;
+  const matures = nowMs + AV_CAPTIME_MS;
+  writeNode(run, id, { o: team, s: 'assaulted', m: matures });
+  return matures;
+}
+
+/** Mature every assault whose clock has run out. Returns the ids that flipped to owned. */
+export function avSettleAssaults(run: InstanceRun, nowMs: number): string[] {
+  const flipped: string[] = [];
+  for (const n of avNodeBoard(run)) {
+    if (n.state !== 'assaulted' || n.maturesAtMs == null) continue;
+    if (nowMs < n.maturesAtMs) continue;
+    writeNode(run, n.id, { o: n.owner, s: 'owned' });
+    flipped.push(n.id);
+  }
+  return flipped;
+}
+
+// ---- mines ----------------------------------------------------------------
+
+export interface AvMineStatus {
+  id: string;
+  name: string;
+  owner: AvTeam | null;
+}
+
+/** Both mines, neutral until a side takes one. Cite: BattleGroundAV.cpp:104-113. */
+export function avMineBoard(run: InstanceRun): AvMineStatus[] {
+  const saved = run.avMines ?? {};
+  return AV_MINES.map((m) => ({ id: m.id, name: m.name, owner: saved[m.id] ?? null }));
+}
+
+export function avSetMineOwner(run: InstanceRun, id: string, team: AvTeam): void {
+  run.avMines = { ...(run.avMines ?? {}), [id]: team };
+}
+
+/**
+ * Pay every held mine's 45 s tick since the last call, and bank the result on the run.
+ * Returns the reinforcements `team` gained this call. Cite: BattleGroundAV.cpp:319-341.
+ */
+export function avMineTick(run: InstanceRun, team: AvTeam, nowMs: number): number {
+  const held = avMineBoard(run).filter((m) => m.owner === team).length;
+  const last = run.avMineTickAtMs ?? nowMs;
+  if (!held) { run.avMineTickAtMs = nowMs; return 0; }
+  const ticks = Math.floor((nowMs - last) / AV_MINE_TICK_MS);
+  if (ticks <= 0) return 0;
+  run.avMineTickAtMs = last + ticks * AV_MINE_TICK_MS;
+  const gained = ticks * held;
+  run.avMineIncome = (run.avMineIncome ?? 0) + gained;
+  return gained;
+}
+
+/** The capture cast a click owes, so a caller never re-derives it. */
+export const AV_ASSAULT_CAST_MS = AV_CAPTURE_CAST_MS;
+/** Match-clock ms an assault needs to mature. */
+export const AV_ASSAULT_MATURE_MS = AV_CAPTIME_MS;
+/** Graveyard a dead raider of `team` should rez at — the held one nearest the corpse. */
+export function avNearestOwnedGraveyard(
+  run: InstanceRun,
+  team: AvTeam,
+  at: { x: number; y: number },
+): AvNodeStatus | null {
+  const held = avNodeBoard(run).filter((n) => n.owner === team && n.state === 'owned');
+  if (!held.length) return null;
+  let best = held[0]!;
+  let bestD = Infinity;
+  for (const n of held) {
+    const d = detHypot(n.x - at.x, n.y - at.y);
+    if (d < bestD) { bestD = d; best = n; }
+  }
+  return best;
+}
+
+/** Start-of-match defaults, so a fresh run shows the DB's own board. */
+export function avSeedBoard(run: InstanceRun): void {
+  if (run.avNodes) return;
+  const seed: Record<string, AvNodeSave> = {};
+  for (const n of avCaptureNodes()) seed[n.id] = { o: n.owner, s: 'owned' };
+  run.avNodes = seed;
+  run.avMines = {};
+  run.avMineTickAtMs = 0;
+  run.avMineIncome = 0;
+  void AV_DATA;
+}