azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/bg/types.ts

@@ -0,0 +1,291 @@
+// Battleground core types — the order-intent layer and the information seam. ONE order-intent
+// layer for input, touch and bots; and a strategy may read ONLY a per-team `BgView`, never more.
+
+import type { CombatantSpec } from '../../engine/combat.ts';
+
+export type BgTeam = 'alliance' | 'horde';
+export type BgUnitId = string;
+
+/** Planar world position on the BG map (the DB's x/y; z is terrain and rides on the unit). */
+export interface BgPos {
+  x: number;
+  y: number;
+}
+
+export const OTHER_TEAM: Readonly<Record<BgTeam, BgTeam>> = Object.freeze({
+  alliance: 'horde',
+  horde: 'alliance',
+});
+
+// §6b: the single order union. Everything that can direct a unit produces one of these. A unit holds
+// exactly one order; issuing a new one replaces it.
+export type BgOrder =
+  | { kind: 'move'; to: BgPos; /** Shift-click: append as a waypoint, don't replace. */ queue?: boolean;
+      /** Raycast the mesh instead of routing a corridor. Cite: PathFinder.cpp:1357 m_straightLine. */
+      straight?: boolean }
+  | { kind: 'attack-move'; to: BgPos }
+  | { kind: 'hold' }
+  | { kind: 'patrol'; waypoints: readonly BgPos[]; index: number }
+  | { kind: 'follow'; target: BgUnitId }
+  | { kind: 'assist'; target: BgUnitId }
+  | { kind: 'use-object'; objectId: string }
+  | { kind: 'cast-on'; spellId: number; target: BgUnitId }
+  | { kind: 'retreat'; to: BgPos };
+
+/** Battle role a strategy assigns. Not a class role — a job on this map. */
+export type BgRole =
+  | 'flag-carrier'
+  | 'fc-escort'
+  | 'offense'
+  | 'defense'
+  | 'mid'
+  | 'flex'
+  /** AB: take the nearest base this team does not hold. */
+  | 'node-assault'
+  /** AB: sit on the base we hold that the enemy is closest to. */
+  | 'node-defense'
+  /** AV: push the enemy line — take the next tower or graveyard toward their keep. */
+  | 'av-offense'
+  /** AV: hold the towers and graveyards behind our line, and the boss room. */
+  | 'av-defense'
+  /** AV: the mine and quest-item economy — the reinforcement tick and the troop upgrades. */
+  | 'av-economy'
+  /** AV: a battleground NPC — a tower guard, a mine trogg, a spirit guide. Never a player seat. */
+  | 'npc-guard'
+  /** AV: a general, a captain or a tower lieutenant — the body a push is aimed at. */
+  | 'npc-commander';
+
+/** A unit in the battleground: human-driven or bot-driven, identically. */
+export interface BgUnit {
+  id: BgUnitId;
+  team: BgTeam;
+  name: string;
+  cls: number;
+  level: number;
+  pos: BgPos;
+  /** Terrain height, carried so the nav mask and the renderer agree. */
+  z: number;
+  hp: number;
+  maxHp: number;
+  /** Dead units hold a respawn deadline; the graveyard cycle revives them (§13b). */
+  deadUntilMs?: number;
+  /** Honorless Target 2479 expiry on the match clock. Cite: Player.cpp:6626; MovementHandler.cpp:241–242. */
+  honorlessUntilMs?: number;
+  role: BgRole;
+  order: BgOrder;
+  /** Combat spec — only needed when a shard is folded into a real createSession. */
+  spec?: CombatantSpec;
+  /** Movement speed, yards/second. */
+  speedYd: number;
+  /** Set while this unit carries an enemy flag (the aura id, 23333 / 23335). */
+  carryingFlag?: number;
+  /** True for a seat a human is driving; bots are false. Interchangeable at any seat (§0). */
+  human: boolean;
+  /** Which engagement shard this unit is currently in, if any. */
+  shard?: number;
+  /**
+   * A battleground NPC rather than a player seat: the creature it is, and the post it holds.
+   * Cite: BattleGroundAV.cpp:114 HandleCreatureCreate — AV's field is creature spawns, not seats.
+   */
+  npc?: BgNpcBody;
+}
+
+/** The NPC half of a BgUnit: which creature, which event slot spawned it, where it stands. */
+export interface BgNpcBody {
+  /** creature_template.Entry. */
+  entry: number;
+  /** `creature_battleground` event1/event2 that owns this body, when it has one. */
+  event1?: number;
+  event2?: number;
+  /** Spawn point — a guard walks back to it and never chases past `leashYd`. */
+  post: BgPos;
+  /** Hostile to BOTH sides in 1.12 — the wildlife and the mine trash. `team` is only the side its
+   *  body fights ON (neutralSideFor); it never makes the body a member of that team's raid. */
+  neutral?: boolean;
+  /** How far it may leave `post` before it turns around. */
+  leashYd: number;
+  /** `creature.spawndist` when MovementType is 1 (MOVEMENT_RANDOM); absent means it stands still.
+   *  Cite: RandomMovementGenerator.cpp:163 WanderMovementGenerator, respawn coord + radius. */
+  wanderYd?: number;
+}
+
+/** A body the player may order: a seat on their own side. An AV creature never is, whichever side
+ *  `neutralSideFor` parked it on. Cite: BattleGroundAV.cpp:114 HandleCreatureCreate. */
+export function isCommandableBy(u: BgUnit, team: BgTeam): boolean {
+  return u.team === team && !u.npc;
+}
+
+/** A map objective — a flag, a node, a tower. Owned or neutral. */
+export interface BgObjective {
+  id: string;
+  kind: 'flag' | 'node' | 'tower' | 'powerup';
+  pos: BgPos;
+  /** Team that currently owns it; null = neutral / contested. */
+  owner: BgTeam | null;
+  /**
+   * For flags: 'base' | 'carried' | 'ground' (WSPickedUpFlagStates). For AB nodes:
+   * 'neutral' | 'assaulted' | 'owned' (ABNodeStatus, BattleGroundAB.h:104-111).
+   */
+  state?: string;
+  /** Unit carrying it, when state === 'carried'. */
+  carrier?: BgUnitId;
+  /**
+   * AB nodes: who held it before the running assault. Cite: BattleGroundAB.cpp:309 — a contested
+   * node whose PREVIOUS status was occupied is defended back, not re-assaulted, so the state
+   * machine cannot be expressed without it.
+   */
+  prevOwner?: BgTeam | null;
+  /**
+   * AV nodes: the last team that DESTROYED this node, which is not the same as owning it.
+   * Cite: BattleGroundAV.h:566 AVNodeInfo.totalOwner — an assault is refused when the assaulting
+   * team is already the totalOwner, and Snowfall stays neutral until somebody first destroys it.
+   */
+  totalOwner?: BgTeam | null;
+  /** AB / AV: the unit whose 10 s banner claim is running, and the clock it completes on. */
+  claimBy?: BgUnitId;
+  claimEndsMs?: number;
+  /** Wall-clock ms this objective's current timer expires (respawn / capture). */
+  timerMs?: number;
+}
+
+// What ONE team may know: own units in full, enemies only as far as they are perceptible. Bots are
+// held to player information at EVERY tier — tiers differ in quality and reaction, never vision.
+export type ScoreType =
+  | 'kills' | 'deaths' | 'honorKills' | 'caps' | 'defends' | 'bonusHonor'
+  | 'gyAssaulted' | 'gyDefended' | 'towersAssaulted' | 'towersDefended'
+  | 'minesCaptured' | 'leadersKilled' | 'secondaryObjectives';
+
+/** One MSG_PVP_LOG_DATA row. Field order and the AV block are BattleGroundMgr.cpp:150-170. */
+export interface BgScoreboardEntry {
+  /** SCORE_KILLING_BLOWS. Cite: BattleGround.h:169-172. */
+  kills: number;
+  deaths: number;
+  honorKills: number;
+  /** SCORE_BONUS_HONOR — RewardHonorToTeam only, never a player kill. Cite: BattleGround.cpp:626. */
+  bonusHonor: number;
+  /** SCORE_FLAG_CAPTURES / *_ASSAULTED. Cite: BattleGround.h:175,:178,:181,:183. */
+  caps: number;
+  /** SCORE_*_DEFENDED — the click that puts a burning point straight back. Cite: .h:179,:182,:184. */
+  defends: number;
+  /** SCORE_GRAVEYARDS_ASSAULTED / _DEFENDED. Cite: BattleGroundAV.cpp:469-473. */
+  gyAssaulted: number;
+  gyDefended: number;
+  /** SCORE_TOWERS_ASSAULTED / _DEFENDED. Cite: BattleGroundAV.cpp:475-479. */
+  towersAssaulted: number;
+  towersDefended: number;
+  /** The client's "Mines Captured": BattleGroundAVScore.secondaryObjectives. Cite: BattleGroundMgr.cpp:162. */
+  minesCaptured: number;
+  /** The client's "Leaders Killed": BattleGroundAVScore.lieutnantCount. Cite: BattleGroundMgr.cpp:168. */
+  leadersKilled: number;
+  /** The client's "Secondary Objectives": BattleGroundAVScore.secondaryNPC. Cite: BattleGroundMgr.cpp:169. */
+  secondaryObjectives: number;
+}
+
+/** A fresh row. One factory, so a new packet field cannot be half-initialised at two call sites. */
+export function emptyBgScore(): BgScoreboardEntry {
+  return {
+    kills: 0, deaths: 0, honorKills: 0, bonusHonor: 0, caps: 0, defends: 0,
+    gyAssaulted: 0, gyDefended: 0, towersAssaulted: 0, towersDefended: 0,
+    minesCaptured: 0, leadersKilled: 0, secondaryObjectives: 0,
+  };
+}
+
+export interface BgView {
+  team: BgTeam;
+  /** Match clock, ms since gates opened (negative during the countdown). */
+  t: number;
+  /** Own team, in full. */
+  own: readonly BgUnitView[];
+  /** Enemies this team can currently perceive. NOT the enemy roster. */
+  enemies: readonly BgUnitView[];
+  objectives: readonly BgObjective[];
+  score: Readonly<Record<BgTeam, number>>;
+  scoreboard: ReadonlyMap<BgUnitId, BgScoreboardEntry>;
+  /** The vision rules this view was built under (§6g config table). */
+  vision: BgVisionConfig;
+}
+
+/** A unit as seen through a view — no spec, no order, no internals. */
+export interface BgUnitView {
+  id: BgUnitId;
+  team: BgTeam;
+  name: string;
+  cls: number;
+  level: number;
+  pos: BgPos;
+  hpPct: number;
+  alive: boolean;
+  role: BgRole;
+  carryingFlag?: number;
+  /** Only present for own units — an enemy's job is not visible. */
+  order?: BgOrder;
+  /** NPCs only: the spawn point it guards. Where a creature stands is not hidden information. */
+  post?: BgPos;
+  /** NPCs only: MOVEMENT_RANDOM radius around `post`, 0 for a body that holds still. */
+  wanderYd?: number;
+}
+
+// Per-tier vision. The seam is architecture; the amount is config (§6g). Defaults are player-equivalent;
+// every field that loosens them is opt-in and logged.
+export interface BgVisionConfig {
+  /** Ignore line of sight — see through terrain. Default false. */
+  seeThroughWalls: boolean;
+  /** Ignore stealth. Default false. */
+  seeStealthed: boolean;
+  /** Hard sight radius in yards. Beyond this an enemy is unseen even in the open. */
+  sightYd: number;
+  /** ms a bot waits before reacting to something new — the honest difficulty axis. */
+  reactionDelayMs: number;
+}
+
+/** Held to player information. The default at every tier. */
+export const FAIR_VISION: BgVisionConfig = Object.freeze({
+  seeThroughWalls: false,
+  seeStealthed: false,
+  sightYd: 100,
+  reactionDelayMs: 0,
+});
+
+// Strategy layer (§6a) — mangosbot relevance idiom, BgView-only
+
+// One thing a team can decide to do with one unit. Mirrors `BotAction` but the signature takes
+// ONLY the view, so it is not possible to write a BG action that reads the opposing roster.
+export interface BgAction {
+  name: string;
+  /** Preference weight when available; higher wins. */
+  relevance(unit: BgUnitView, view: BgView): number;
+  /** Trigger: is this worth doing for this unit right now? */
+  available(unit: BgUnitView, view: BgView): boolean;
+  /** The order to issue. Returning null falls through to the next action. */
+  order(unit: BgUnitView, view: BgView): BgOrder | null;
+}
+
+/** A toggleable, named bundle of actions (mangosbot strategy). */
+export interface BgStrategy {
+  name: string;
+  actions: readonly BgAction[];
+}
+
+/** Flatten active bundles to the action list the policy chooses from. */
+export function bgActionsOf(strategies: readonly BgStrategy[]): BgAction[] {
+  return strategies.flatMap((s) => [...s.actions]);
+}
+
+// Pick the highest-relevance available action for one unit and return its order. Ties break on action
+// order, so a bundle list is a priority list.
+export function pickBgOrder(
+  unit: BgUnitView,
+  view: BgView,
+  actions: readonly BgAction[],
+): { order: BgOrder; action: string } | null {
+  let best: { order: BgOrder; action: string; rel: number } | null = null;
+  for (const a of actions) {
+    if (!a.available(unit, view)) continue;
+    const rel = a.relevance(unit, view);
+    if (best && rel <= best.rel) continue;
+    const order = a.order(unit, view);
+    if (!order) continue;
+    best = { order, action: a.name, rel };
+  }
+  return best ? { order: best.order, action: best.action } : null;
+}

package/src/domain/bg/wsg.ts

@@ -0,0 +1,264 @@
+// Warsong Gulch (map 489). Every constant is sourced — BattleGroundWS.h:29-31, :54-59, :124-130,
+// battleground_template 2, world_safe_locs 769-772. Carrying the flag IS aura 23333 / 23335.
+
+import type { BgPos, BgTeam, BgUnit } from './types.ts';
+import { OTHER_TEAM } from './types.ts';
+import type { BgWorld } from './bgWorld.ts';
+import { detHypot } from '../../engine/core/detMath.ts';
+
+/** Cite: BattleGroundWS.h:29-31 enum WSTimers. */
+export const WS_MAX_TEAM_SCORE = 3;
+export const WS_FLAG_RESPAWN_MS = 23_000;
+export const WS_FLAG_DROP_MS = 10_000;
+
+/** Cite: BattleGroundWS.h:54-59 enum WSSpells. */
+export const WS_SPELL_WARSONG_FLAG = 23333;
+export const WS_SPELL_WARSONG_FLAG_DROPPED = 23334;
+export const WS_SPELL_SILVERWING_FLAG = 23335;
+export const WS_SPELL_SILVERWING_FLAG_DROPPED = 23336;
+
+/** Cite: BattleGroundWS.h:124-130 enum WSGameObjects. */
+export const GO_WS_SILVERWING_FLAG = 179830;
+export const GO_WS_WARSONG_FLAG = 179831;
+export const GO_WS_SILVERWING_FLAG_DROP = 179785;
+export const GO_WS_WARSONG_FLAG_DROP = 179786;
+
+/** Cite: BattleGroundWS.h:186-187. Index by bgBracketId(level, 10, 60). */
+export const WS_FLAG_CAPTURED_HONOR = [48, 82, 136, 226, 378, 396] as const;
+export const WS_WIN_MATCH_HONOR = [24, 41, 68, 113, 189, 198] as const;
+
+/** How close you must be to pick up or capture. The client uses GO interaction range. */
+export const WS_FLAG_INTERACT_YD = 6;
+
+// Real coordinates, `gameobject` @ map 489 and `world_safe_locs`. Alliance holds Silverwing (east, +x);
+// Horde holds Warsong (west).
+export const WSG_GEOMETRY = Object.freeze({
+  flagBase: {
+    alliance: { x: 1540.4, y: 1481.3, z: 351.8 }, // GO 179830 Silverwing
+    horde: { x: 916.5, y: 1433.8, z: 346.4 },     // GO 179831 Warsong
+  },
+  start: {
+    alliance: { x: 1519.53, y: 1481.87, z: 352.024 }, // world_safe_locs 769
+    horde: { x: 933.331, y: 1433.72, z: 345.536 },    // world_safe_locs 770
+  },
+  graveyard: {
+    alliance: { x: 1415.33, y: 1554.79, z: 343.156 }, // 771 Alliance Rez
+    horde: { x: 1029.14, y: 1387.49, z: 340.836 },    // 772 Horde Rez
+  },
+  /** Field buffs — Buff_Entries[3], 180 s respawn (BattleGround.h:111-122). */
+  powerups: [
+    { id: 'speed-a', entry: 179871, x: 1449.9, y: 1470.7 },
+    { id: 'speed-h', entry: 179871, x: 1005.2, y: 1448.0 },
+    { id: 'regen-a', entry: 179904, x: 1317.5, y: 1550.8 },
+    { id: 'regen-h', entry: 179904, x: 1110.5, y: 1353.7 },
+    { id: 'zerk-a', entry: 179905, x: 1320.1, y: 1378.8 },
+    { id: 'zerk-h', entry: 179905, x: 1139.7, y: 1560.3 },
+  ],
+  /** Rough field centre — the mid-map contest point strategies aim at. */
+  mid: { x: 1228, y: 1457 },
+});
+
+export const WS_POWERUP_RESPAWN_MS = 180_000;
+
+// Powerup GO → the spell its trap casts on whoever walks over it. Cite: gameobject_template type 6
+// data3 for 179871 / 179904 / 179905; BattleGround.cpp HandleTriggerBuff.
+export const WS_BUFF_SPELL_BY_ENTRY: Readonly<Record<number, number>> = Object.freeze({
+  179871: 23451, // Speed (+100% for 10 s)
+  179904: 23493, // Restoration (periodic 10%/s — CMaNGOS scripted special)
+  179905: 23505, // Berserking (+30% damage done, +10% physical taken, 60 s)
+});
+
+/** The flag a team CARRIES is the enemy's; the flag it DEFENDS is its own. */
+export function flagSpellCarriedBy(team: BgTeam): number {
+  // Alliance carries the Warsong (Horde) flag. Cite: wsgFlagData / WSSpells pairing.
+  return team === 'alliance' ? WS_SPELL_WARSONG_FLAG : WS_SPELL_SILVERWING_FLAG;
+}
+
+/** Objective id for a team's own flag. */
+export function flagObjectiveId(team: BgTeam): string {
+  return `flag-${team}`;
+}
+
+export interface WsgEvent {
+  t: number;
+  kind: 'pickup' | 'drop' | 'return' | 'capture' | 'respawn' | 'score' | 'powerup';
+  team: BgTeam;
+  unit?: string;
+  score?: Record<BgTeam, number>;
+  /** powerup only: the GO entry taken (WS_BUFF_SPELL_BY_ENTRY maps it to the spell). */
+  entry?: number;
+}
+
+// Install WSG rules onto a world: objectives, the flag state machine and the win condition.
+// Returns the event log, the same pure seeded contract combat uses, so a replay reads it too.
+export function installWsg(world: BgWorld): WsgEvent[] {
+  const events: WsgEvent[] = [];
+  const g = WSG_GEOMETRY;
+
+  world.startPos.alliance = { x: g.start.alliance.x, y: g.start.alliance.y };
+  world.startPos.horde = { x: g.start.horde.x, y: g.start.horde.y };
+  world.graveyardOf = wsgGraveyard;
+
+  for (const team of ['alliance', 'horde'] as const) {
+    world.addObjective({
+      id: flagObjectiveId(team),
+      kind: 'flag',
+      pos: { x: g.flagBase[team].x, y: g.flagBase[team].y },
+      owner: team,
+      state: 'base',
+    });
+  }
+  for (const p of g.powerups) {
+    world.addObjective({
+      id: p.id,
+      kind: 'powerup',
+      pos: { x: p.x, y: p.y },
+      owner: null,
+      state: 'up',
+    });
+  }
+
+  const baseOf = (team: BgTeam): BgPos => ({ x: g.flagBase[team].x, y: g.flagBase[team].y });
+
+  const log = (e: WsgEvent): void => {
+    events.push(e);
+  };
+
+  /** Drop the flag `unit` is carrying at its feet, with the 10 s pickup window. */
+  const dropFlag = (unit: BgUnit): void => {
+    const spell = unit.carryingFlag;
+    if (!spell) return;
+    // The flag being carried belongs to the OTHER team.
+    const owner = OTHER_TEAM[unit.team];
+    const obj = world.objectives.get(flagObjectiveId(owner));
+    if (!obj) return;
+    obj.state = 'ground';
+    obj.pos = { x: unit.pos.x, y: unit.pos.y };
+    obj.carrier = undefined;
+    obj.timerMs = world.t + WS_FLAG_DROP_MS;
+    unit.carryingFlag = undefined;
+    log({ t: world.t, kind: 'drop', team: unit.team, unit: unit.id });
+  };
+
+  const returnFlag = (owner: BgTeam, byUnit?: BgUnit): void => {
+    const obj = world.objectives.get(flagObjectiveId(owner));
+    if (!obj) return;
+    obj.state = 'base';
+    obj.pos = baseOf(owner);
+    obj.carrier = undefined;
+    obj.timerMs = undefined;
+    log({ t: world.t, kind: 'return', team: owner, unit: byUnit?.id });
+  };
+
+  world.onTick = (w) => {
+    if (w.ended || !w.gatesOpen) return;
+
+    // A carrier that died drops the flag where it fell.
+    for (const u of w.units.values()) {
+      if (u.carryingFlag && !w.alive(u)) dropFlag(u);
+    }
+
+    for (const team of ['alliance', 'horde'] as const) {
+      const obj = w.objectives.get(flagObjectiveId(team));
+      if (!obj) continue;
+
+      // A dropped flag returns itself after 10 s. Cite: BG_WS_FLAG_DROP_TIME.
+      if (obj.state === 'ground' && obj.timerMs != null && w.t >= obj.timerMs) {
+        returnFlag(team);
+        continue;
+      }
+      // A captured flag respawns at its base after 23 s. Cite: BG_WS_FLAG_RESPAWN_TIME.
+      if (obj.state === 'respawning' && obj.timerMs != null && w.t >= obj.timerMs) {
+        obj.state = 'base';
+        obj.pos = baseOf(team);
+        obj.timerMs = undefined;
+        log({ t: w.t, kind: 'respawn', team });
+        continue;
+      }
+
+      if (obj.state !== 'base' && obj.state !== 'ground') continue;
+
+      // Someone standing on it either takes it (enemy) or returns it (owner, dropped only).
+      for (const u of w.units.values()) {
+        if (!w.alive(u)) continue;
+        if (detHypot(u.pos.x - obj.pos.x, u.pos.y - obj.pos.y) > WS_FLAG_INTERACT_YD) continue;
+
+        if (u.team === team) {
+          // Your own flag: on the ground → return it. At base → nothing.
+          if (obj.state === 'ground') {
+            returnFlag(team, u);
+            break;
+          }
+          continue;
+        }
+        // Enemy flag: pick it up. One flag per unit.
+        if (u.carryingFlag) continue;
+        obj.state = 'carried';
+        obj.carrier = u.id;
+        u.carryingFlag = flagSpellCarriedBy(u.team);
+        log({ t: w.t, kind: 'pickup', team: u.team, unit: u.id });
+        break;
+      }
+    }
+
+    // A carrier standing on its OWN flag, with that flag at base, scores.
+    // Cite: BattleGroundWS.cpp HandleAreaTrigger + "own flag must be at base".
+    for (const u of w.units.values()) {
+      if (!u.carryingFlag || !w.alive(u)) continue;
+      const ownFlag = w.objectives.get(flagObjectiveId(u.team));
+      if (!ownFlag || ownFlag.state !== 'base') continue;
+      const home = baseOf(u.team);
+      if (detHypot(u.pos.x - home.x, u.pos.y - home.y) > WS_FLAG_INTERACT_YD) continue;
+
+      const captured = OTHER_TEAM[u.team];
+      const capturedObj = w.objectives.get(flagObjectiveId(captured));
+      if (capturedObj) {
+        capturedObj.state = 'respawning';
+        capturedObj.carrier = undefined;
+        capturedObj.pos = baseOf(captured);
+        capturedObj.timerMs = w.t + WS_FLAG_RESPAWN_MS;
+      }
+      u.carryingFlag = undefined;
+      w.score[u.team] += 1;
+      w.updatePlayerScore(u.id, 'caps', 1);
+      log({ t: w.t, kind: 'capture', team: u.team, unit: u.id });
+      log({ t: w.t, kind: 'score', team: u.team, score: { ...w.score } });
+
+      if (w.score[u.team] >= WS_MAX_TEAM_SCORE) {
+        w.ended = true;
+        w.winner = u.team;
+      }
+      break;
+    }
+
+    // Powerups: walk over one to take it (trap trigger), 180 s respawn.
+    // Cite: BattleGround.cpp HandleTriggerBuff; BattleGround.h Buff_Entries respawn.
+    for (const o of w.objectives.values()) {
+      if (o.kind !== 'powerup') continue;
+      if (o.state === 'down' && o.timerMs != null && w.t >= o.timerMs) {
+        o.state = 'up';
+        o.timerMs = undefined;
+        continue;
+      }
+      if (o.state !== 'up') continue;
+      const entry = WSG_GEOMETRY.powerups.find((p) => p.id === o.id)?.entry;
+      if (entry == null) continue;
+      for (const u of w.units.values()) {
+        if (!w.alive(u)) continue;
+        if (detHypot(u.pos.x - o.pos.x, u.pos.y - o.pos.y) > WS_FLAG_INTERACT_YD) continue;
+        o.state = 'down';
+        o.timerMs = w.t + WS_POWERUP_RESPAWN_MS;
+        log({ t: w.t, kind: 'powerup', team: u.team, unit: u.id, entry });
+        break;
+      }
+    }
+  };
+
+  return events;
+}
+
+/** Where a dead unit of `team` comes back. Cite: world_safe_locs 771 / 772. */
+export function wsgGraveyard(team: BgTeam): BgPos {
+  const gy = WSG_GEOMETRY.graveyard[team];
+  return { x: gy.x, y: gy.y };
+}

package/src/domain/bots/actionProviderSpec.ts

@@ -0,0 +1,38 @@
+// A companion's action provider as PLAIN DATA (PERF-RUNSHEET S6b). `companionActionProvider` closes
+// over a live `Companion` and two ds lookups; none of that survives a `postMessage`, and the worker
+// has to build the same brain from something it can be handed.
+
+import type { Rotation } from '../rotation/types.ts';
+import type { AllyActionProvider } from '../../engine/combat/types.ts';
+import type { SpellDef } from '../../data/schema.ts';
+import { companionActionProvider } from './companionRotation.ts';
+import { isMultiTargetCombatSpell } from '../rotation/classify.ts';
+import { isCompanionKeepUpSpell } from './companionRotation.ts';
+
+/** Everything `buildActionProvider` needs, all of it structured-cloneable. */
+export type ActionProviderSpec = {
+  rotation: Rotation;
+  /** Boss entry the encounter rows are looked up for, when there is one. */
+  targetEntry?: number;
+  // The PLAYER's two knobs, fixed for the fight (combatSession.ts autoCfgForPlayer). A companion's
+  // arrive per tick instead and are never here.
+  aoeMode?: 'aoe' | 'single' | 'auto';
+  offHealAllowed?: boolean;
+};
+
+/** The one ds-shaped dependency: a spell by id. A worker supplies its own. */
+export type ProviderSpells = { spell: (id: number) => SpellDef | undefined };
+
+// Build the brain from the spec plus a spell store. The AoE and off-heal knobs are NOT here: they
+// change mid-fight, so they arrive per tick as `SimTickInputs.companionKnobs` and the engine stamps them.
+export function buildActionProvider(
+  spec: ActionProviderSpec,
+  ds: ProviderSpells,
+): AllyActionProvider {
+  return companionActionProvider(spec.rotation, spec.targetEntry, {
+    ...(spec.aoeMode != null ? { aoeMode: spec.aoeMode } : {}),
+    ...(spec.offHealAllowed != null ? { offHealAllowed: spec.offHealAllowed } : {}),
+    isMultiSpell: (id) => isMultiTargetCombatSpell(ds.spell(id)),
+    isOocKeepUp: (id) => isCompanionKeepUpSpell(ds.spell(id)),
+  });
+}