azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/creature/faction.ts

@@ -0,0 +1,287 @@
+// Faction reaction between the player and any creature, ported from CMaNGOS Relations.cpp. The
+// player's template is derived from their race, so it needs no save migration. Pure domain.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { FactionTemplateDef } from '../../data/schema.ts';
+import { REP_RANK, type ReputationRank } from './reputation.ts';
+import { isSyntheticClassTrainerEntry } from '../economy/syntheticClassTrainers.ts';
+import { unitImmuneToPlayer } from './unitFlags.ts';
+
+/** FactionGroupMask — the Alliance/Horde/Player/Monster bits on a template's group masks.
+ *  Cite: DBCEnums.h FactionGroupMask. */
+export const FACTION_GROUP_MASK = {
+  PLAYER: 1,
+  ALLIANCE: 2,
+  HORDE: 4,
+  MONSTER: 8,
+} as const;
+
+/** Cite: Unit.h:509-525 NPCFlags. Gossip/vendor/trainer never participate in CanAttack. */
+export const UNIT_NPC_FLAG = {
+  NONE: 0x00000000,
+  GOSSIP: 0x00000001,
+  QUESTGIVER: 0x00000002,
+  VENDOR: 0x00000004,
+  FLIGHTMASTER: 0x00000008,
+  TRAINER: 0x00000010,
+  SPIRITHEALER: 0x00000020,
+  SPIRITGUIDE: 0x00000040,
+  INNKEEPER: 0x00000080,
+  BANKER: 0x00000100,
+  PETITIONER: 0x00000200,
+  TABARDDESIGNER: 0x00000400,
+  BATTLEMASTER: 0x00000800,
+  AUCTIONEER: 0x00001000,
+  STABLEMASTER: 0x00002000,
+  REPAIR: 0x00004000,
+  OUTDOORPVP: 0x20000000,
+} as const;
+
+export function npcFlagBits(npcFlags: number): {
+  gossip: boolean;
+  vendor: boolean;
+  trainer: boolean;
+  questgiver: boolean;
+} {
+  const f = npcFlags | 0;
+  return {
+    gossip: (f & UNIT_NPC_FLAG.GOSSIP) !== 0,
+    vendor: (f & UNIT_NPC_FLAG.VENDOR) !== 0,
+    trainer: (f & UNIT_NPC_FLAG.TRAINER) !== 0,
+    questgiver: (f & UNIT_NPC_FLAG.QUESTGIVER) !== 0,
+  };
+}
+
+// Template-vs-template reaction, a direct port of GetFactionReaction: asymmetric, enemy before
+// friend, with `a` the acting unit. Evaluation order is load-bearing.
+export function getFactionReaction(a: FactionTemplateDef, b: FactionTemplateDef): ReputationRank {
+  // 1. other is in a group we treat as an enemy
+  if (b.ourMask & a.enemyMask) return REP_RANK.HOSTILE;
+  // 2. other's identity is on our explicit enemy list
+  if (b.faction && a.enemyFactions.includes(b.faction)) return REP_RANK.HOSTILE;
+  // 3. other is in a group we treat as a friend
+  if (b.ourMask & a.friendMask) return REP_RANK.FRIENDLY;
+  // 4. other's identity is on our explicit friend list
+  if (b.faction && a.friendFactions.includes(b.faction)) return REP_RANK.FRIENDLY;
+  // 5. we are in a group the other treats as a friend
+  if (a.ourMask & b.friendMask) return REP_RANK.FRIENDLY;
+  // 6. our identity is on the other's explicit friend list
+  if (a.faction && b.friendFactions.includes(a.faction)) return REP_RANK.FRIENDLY;
+  return REP_RANK.NEUTRAL;
+}
+
+/** The player's FactionTemplate id, derived from their race (ChrRaces.FactionID). */
+export function playerFactionTemplateId(ds: DataStore, race: number): number | undefined {
+  return ds.race(race)?.factionTemplate;
+}
+
+/** The player's faction template row (undefined when the race/bundle predates the faction bake). */
+function playerTemplate(ds: DataStore, race: number): FactionTemplateDef | undefined {
+  const id = playerFactionTemplateId(ds, race);
+  return id != null ? ds.factionTemplate(id) : undefined;
+}
+
+// SPELL_AURA_FORCE_REACTION (139) map: Faction.dbc id → forced rank. Not a faction swap and not
+// keyed by template id, since GetForcedRankIfAny reads ->faction. Cite: ReputationMgr.cpp:123.
+export type ForcedReactions = ReadonlyMap<number, ReputationRank>;
+
+// The forced rank for a creature template when the player carries a matching force_reaction aura.
+// Both directions short-circuit on this before any faction math. Cite: Relations.cpp:171, :237.
+function forcedRankFor(
+  ds: DataStore,
+  creatureFactionTemplate: number | undefined,
+  forced: ForcedReactions | undefined,
+): ReputationRank | undefined {
+  if (!forced?.size || creatureFactionTemplate == null) return undefined;
+  const t = ds.factionTemplate(creatureFactionTemplate);
+  return t ? forced.get(t.faction | 0) : undefined;
+}
+
+// How a creature (by its faction-template id) reacts to a player of the given race. Undefined when either
+// template is missing — callers should fail open (treat unknown as interactable).
+export function creatureReactionToPlayer(
+  ds: DataStore,
+  race: number,
+  creatureFactionTemplate: number,
+  forced?: ForcedReactions,
+): ReputationRank | undefined {
+  const forcedRank = forcedRankFor(ds, creatureFactionTemplate, forced);
+  if (forcedRank != null) return forcedRank;
+  const player = playerTemplate(ds, race);
+  const creature = ds.factionTemplate(creatureFactionTemplate);
+  if (!player || !creature) return undefined;
+  return getFactionReaction(creature, player);
+}
+
+// The Faction.dbc identity behind a creature's faction template — the id the reputation pane tracks, so a
+// war declared there can be matched against the NPC in front of you.
+export function creatureRepFactionId(ds: DataStore, creatureEntry: number): number | undefined {
+  const ft = ds.creature(creatureEntry)?.factionId;
+  if (ft == null) return undefined;
+  const faction = ds.factionTemplate(ft)?.faction;
+  return faction || undefined;
+}
+
+/** True when the player has declared war on the faction this creature belongs to. */
+export function isAtWarWithCreature(
+  ds: DataStore,
+  creatureEntry: number,
+  atWar: ReadonlySet<number> | undefined,
+): boolean {
+  if (!atWar || atWar.size === 0) return false;
+  const faction = creatureRepFactionId(ds, creatureEntry);
+  return faction != null && atWar.has(faction);
+}
+
+// Whether a player of `race` may interact with an NPC of this faction template: the reaction must
+// beat Unfriendly BOTH ways. Service NPCs fail CLOSED on missing data, others fail open (KI-433).
+export function canInteractWithFactionTemplate(
+  ds: DataStore,
+  race: number,
+  creatureFactionTemplate: number | undefined,
+  requireFaction = false,
+  forced?: ForcedReactions,
+): boolean {
+  if (creatureFactionTemplate == null) return !requireFaction;
+  // A forced rank replaces BOTH directions — Relations.cpp returns it before the template math.
+  const forcedRank = forcedRankFor(ds, creatureFactionTemplate, forced);
+  if (forcedRank != null) return forcedRank > REP_RANK.UNFRIENDLY;
+  const player = playerTemplate(ds, race);
+  const creature = ds.factionTemplate(creatureFactionTemplate);
+  if (!player || !creature) return !requireFaction;
+  return (
+    getFactionReaction(player, creature) > REP_RANK.UNFRIENDLY &&
+    getFactionReaction(creature, player) > REP_RANK.UNFRIENDLY
+  );
+}
+
+// Synthetic class trainers are not creature_template rows (entry = 1000*1000+cls; legacy 1000+cls).
+// Interaction must not inherit a colliding mob's faction. Cite: syntheticClassTrainers.ts; KI-918.
+function isSyntheticClassTrainer(ds: DataStore, entry: number): boolean {
+  return isSyntheticClassTrainerEntry(entry) && ds.trainer(entry) != null;
+}
+
+/** Vendors / class trainers / profession trainers — service interaction needs a known faction. */
+function isServiceNpc(ds: DataStore, entry: number): boolean {
+  return ds.vendor(entry) != null || ds.trainer(entry) != null || ds.profTrainer(entry) != null;
+}
+
+// Gate by a concrete NPC entry, resolving its factionId. Synthetic class trainers always pass;
+// service NPCs fail closed on a missing faction so enemy stock cannot be bought (KI-433).
+export function canInteractWithCreature(
+  ds: DataStore,
+  race: number,
+  creatureEntry: number,
+  atWar?: ReadonlySet<number>,
+  forced?: ForcedReactions,
+): boolean {
+  if (isSyntheticClassTrainer(ds, creatureEntry)) return true;
+  // A war you declared in the reputation pane closes every door that faction owns.
+  if (isAtWarWithCreature(ds, creatureEntry, atWar)) return false;
+  const requireFaction = isServiceNpc(ds, creatureEntry);
+  return canInteractWithFactionTemplate(
+    ds,
+    race,
+    ds.creature(creatureEntry)?.factionId,
+    requireFaction,
+    forced,
+  );
+}
+
+// A template at war with nobody: no enemy group bit and no explicit enemy faction, so
+// GetFactionReaction can never return hostile for it against anything. Faction template 35
+// "Friendly" is the shape, and it is what every credit marker and herald on a battleground map
+// carries. Cite: Relations.cpp:351-368 — hostility only ever comes from enemyMask/enemyFactions.
+export function factionHasNoEnemies(ft: FactionTemplateDef): boolean {
+  return (ft.enemyMask | 0) === 0 && ft.enemyFactions.length === 0;
+}
+
+// True when a creature is actively hostile to the player — the case that blocks interaction and
+// marks the NPC as an enemy. Fails closed, so it never invents aggression the data lacks.
+export function isHostileCreature(
+  ds: DataStore,
+  race: number,
+  creatureEntry: number,
+  forced?: ForcedReactions,
+): boolean {
+  const ft = ds.creature(creatureEntry)?.factionId;
+  const reaction = ft != null ? creatureReactionToPlayer(ds, race, ft, forced) : undefined;
+  return reaction != null && reaction < REP_RANK.UNFRIENDLY;
+}
+
+// True when the reaction is Friendly or better — floor bodies that must never be attacked. Fails
+// closed so unknowns stay attackable via canAttack. Cite: Relations.cpp IsFriendlyTo.
+export function isFriendlyCreature(
+  ds: DataStore,
+  race: number,
+  creatureEntry: number,
+  forced?: ForcedReactions,
+): boolean {
+  const ft = ds.creature(creatureEntry)?.factionId;
+  if (ft == null) return false;
+  const reaction = creatureReactionToPlayer(ds, race, ft, forced);
+  return reaction != null && reaction >= REP_RANK.FRIENDLY;
+}
+
+// Whether the player may start combat with this creature. Friendly+ cannot be attacked; Neutral
+// and worse can. Fails OPEN on missing faction data so legacy templates stay grindable.
+export function canAttackCreature(
+  ds: DataStore,
+  race: number,
+  creatureEntry: number,
+  atWar?: ReadonlySet<number>,
+  forced?: ForcedReactions,
+): boolean {
+  // At war = fair game, even for a faction that would otherwise be friendly (the Bloodsail /
+  // Steamwheedle bargain). Cite: Unit::CanAttack — at-war state overrides the friendly reaction.
+  if (isAtWarWithCreature(ds, creatureEntry, atWar)) return true;
+  const ft = ds.creature(creatureEntry)?.factionId;
+  if (ft == null) return true;
+  const reaction = creatureReactionToPlayer(ds, race, ft, forced);
+  if (reaction == null) return true;
+  return reaction < REP_RANK.FRIENDLY;
+}
+
+// Peaceful gossip/vendor/trainer click. npcFlags ≠ 0 and CanInteract (reaction > UNFRIENDLY both ways).
+// Independent of CanAttack. Cite: Relations.cpp:586-608 Unit::CanInteract.
+export function canTalkToCreature(
+  ds: DataStore,
+  race: number,
+  creatureEntry: number,
+  npcFlags: number,
+  atWar?: ReadonlySet<number>,
+  forced?: ForcedReactions,
+): boolean {
+  if ((npcFlags | 0) === 0) return false;
+  return canInteractWithCreature(ds, race, creatureEntry, atWar, forced);
+}
+
+export type NpcClickContract = {
+  talk: boolean;
+  attack: boolean;
+  both: boolean;
+  hostile: boolean;
+};
+
+// Click contract: gossip flags and attackability are independent. Talk = npcFlags + CanInteract. Attack =
+// CanAttack (flags never exclude). Cite: Relations.cpp:414 CanAttack !IsFriend; :608 CanInteract.
+export function npcClickContract(
+  ds: DataStore,
+  race: number,
+  creatureEntry: number,
+  npcFlags: number,
+  atWar?: ReadonlySet<number>,
+  forced?: ForcedReactions,
+): NpcClickContract {
+  const talk = canTalkToCreature(ds, race, creatureEntry, npcFlags, atWar, forced);
+  // A neutral vendor with UNIT_FLAG_IMMUNE_TO_PLAYER (Lokhtos 12944) offers no Attack; a body an
+  // event already turned hostile is engaged by the aggro path, never by this click. Cite: Relations.cpp:373-374.
+  const attack = canAttackCreature(ds, race, creatureEntry, atWar, forced)
+    && !unitImmuneToPlayer(ds.creature(creatureEntry));
+  return {
+    talk,
+    attack,
+    both: talk && attack,
+    hostile: isHostileCreature(ds, race, creatureEntry, forced),
+  };
+}

package/src/domain/creature/forcedReaction.ts

@@ -0,0 +1,48 @@
+// SPELL_AURA_FORCE_REACTION (139) player state — the map every reaction check consults. Not a
+// faction swap: it stores Faction.dbc id → rank, so one entry covers every matching template.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ForcedReactions } from './faction.ts';
+import type { ReputationRank } from './reputation.ts';
+
+/** Serialized form on the run (`faction id -> rank`), so it survives a save. */
+export type ForcedReactionMap = Record<number, number>;
+
+/** The `force_reaction` effects a spell carries, if any. */
+export function forceReactionsOfSpell(
+  ds: DataStore,
+  spellId: number,
+): { factionId: number; rank: ReputationRank }[] {
+  const out: { factionId: number; rank: ReputationRank }[] = [];
+  for (const eff of ds.spell(spellId)?.effects ?? []) {
+    if (eff.kind !== 'force_reaction') continue;
+    const factionId = (eff as { factionId?: number }).factionId ?? 0;
+    if (!factionId) continue;
+    const rank = ((eff as { reputationRank?: number }).reputationRank ?? 0) as ReputationRank;
+    out.push({ factionId, rank });
+  }
+  return out;
+}
+
+// Build the forced map from the aura spells on the player. Highest rank wins when two auras name
+// the same faction, since the C++ overwrite depends on an apply order a rebuilt set lacks.
+export function forcedReactionsFrom(
+  ds: DataStore,
+  activeSpellIds: Iterable<number>,
+): ForcedReactionMap {
+  const map: ForcedReactionMap = {};
+  for (const id of activeSpellIds) {
+    for (const { factionId, rank } of forceReactionsOfSpell(ds, id)) {
+      if (map[factionId] == null || rank > map[factionId]!) map[factionId] = rank;
+    }
+  }
+  return map;
+}
+
+/** Read a persisted map back as the `ForcedReactions` the faction API takes. Empty → undefined. */
+export function forcedReactionsOf(map: ForcedReactionMap | undefined): ForcedReactions | undefined {
+  if (!map) return undefined;
+  const out = new Map<number, ReputationRank>();
+  for (const [k, v] of Object.entries(map)) out.set(Number(k), v as ReputationRank);
+  return out.size ? out : undefined;
+}

package/src/domain/creature/outdoorHuntable.ts

@@ -0,0 +1,74 @@
+// Outdoor grind eligibility for the zone.huntable runtime prune. Quest-kill must not punch
+// CIVILIAN, faction-35 or same-side noXp through. Cite: zone-derive.mjs:89–164; Creature.h:56.
+
+import type { FactionTemplateDef } from '../../data/schema.ts';
+import { FACTION_GROUP_MASK } from './faction.ts';
+import { CREATURE_EXTRA_FLAG } from './creatureAiConstants.ts';
+import { unitCannotBeAttacked, type UnitFlagsBearer } from './unitFlags.ts';
+
+/** FactionTemplate.dbc id 35 — PLAYER / Friendly. Pets, Binding VW, credit doodads. */
+export const FRIENDLY_PLAYER_FACTION_TEMPLATE = 35;
+
+/** CreatureType 8. Cite: SharedDefines.h CREATURE_TYPE_CRITTER. */
+export const CREATURE_TYPE_CRITTER = 8;
+
+/** Bits that mean "not a yellow-name grind target" even when quest-kill listed them. */
+export const OUTDOOR_NONGRIND_EXTRA =
+  CREATURE_EXTRA_FLAG.CIVILIAN | CREATURE_EXTRA_FLAG.INVISIBLE;
+
+export const PLAYER_FACTION_GROUPS =
+  FACTION_GROUP_MASK.PLAYER | FACTION_GROUP_MASK.ALLIANCE | FACTION_GROUP_MASK.HORDE;
+
+export type OutdoorHuntableCreature = UnitFlagsBearer & {
+  factionId?: number;
+  noXp?: boolean;
+  extraFlags?: number;
+  creatureType?: number;
+};
+
+export type ZoneFactionSide = 'alliance' | 'horde' | 'contested' | undefined;
+
+export function isFriendlyPlayerFactionTemplate(factionId: number | undefined): boolean {
+  return ((factionId ?? 0) | 0) === FRIENDLY_PLAYER_FACTION_TEMPLATE;
+}
+
+export function isPlayerFactionGroup(ourMask: number): boolean {
+  return (ourMask & PLAYER_FACTION_GROUPS) !== 0;
+}
+
+export function extraFlagsBlockOutdoorGrind(extraFlags: number | undefined): boolean {
+  return ((extraFlags ?? 0) & OUTDOOR_NONGRIND_EXTRA) !== 0;
+}
+
+// Same-side noXp NPC in an Alliance or Horde zone — rescue patients, NO_XP city guards, garment
+// heal proxies. Wildlife noXp has no ALLIANCE/HORDE group bit, so it stays.
+export function isSameSideNoXp(
+  noXp: boolean | undefined,
+  factionTemplate: FactionTemplateDef | null | undefined,
+  zoneFaction: ZoneFactionSide,
+): boolean {
+  if (!noXp || !factionTemplate) return false;
+  if (zoneFaction === 'alliance') {
+    return (factionTemplate.ourMask & FACTION_GROUP_MASK.ALLIANCE) !== 0;
+  }
+  if (zoneFaction === 'horde') {
+    return (factionTemplate.ourMask & FACTION_GROUP_MASK.HORDE) !== 0;
+  }
+  return false;
+}
+
+// True → drop from outdoor zone.huntable. Fail open on a missing creature (lazy catalog) — huntableEntryOk
+// already does.
+export function isOutdoorNonGrindCreature(
+  c: OutdoorHuntableCreature | null | undefined,
+  factionTemplate: FactionTemplateDef | null | undefined,
+  zoneFaction?: ZoneFactionSide,
+): boolean {
+  if (!c) return false;
+  if (((c.creatureType ?? 0) | 0) === CREATURE_TYPE_CRITTER) return true;
+  if (isFriendlyPlayerFactionTemplate(c.factionId)) return true;
+  if (extraFlagsBlockOutdoorGrind(c.extraFlags)) return true;
+  if (unitCannotBeAttacked(c)) return true;
+  if (isSameSideNoXp(c.noXp, factionTemplate, zoneFaction)) return true;
+  return false;
+}

package/src/domain/creature/patrolPacks.ts

@@ -0,0 +1,210 @@
+// A patrol is a PACK: FLAG_FOLLOW slaves hold their spawn offset behind a patrolling master, and a
+// spawn_group_formation walks its own waypoint_path in shape. Rows: creaturePatrolPacks.json.
+
+import packsJson from '../../data/tables/creaturePatrolPacks.json' with { type: 'json' };
+import { detAtan2, detCos, detSin } from '../../engine/core/detMath.ts';
+
+/** SpawnGroupFormationType. Cite: SpawnGroupDefines.h:128-138 (0 = RANDOM, the default arm). */
+export const FORMATION_SINGLE_FILE = 1;
+export const FORMATION_SIDE_BY_SIDE = 2;
+export const FORMATION_LIKE_GEESE = 3;
+export const FORMATION_FANNED_OUT_BEHIND = 4;
+export const FORMATION_FANNED_OUT_IN_FRONT = 5;
+export const FORMATION_CIRCLE_THE_LEADER = 6;
+
+/** MotionMaster.h:54 — a linear path is walked out and back; 2 (WAYPOINT) loops. */
+export const LINEAR_WP_MOTION_TYPE = 4;
+
+/** [x, y, z, o, waitMs, scriptId] — waypoint_path row, in world yards. */
+type PackPathRow = readonly [number, number, number, number, number, number];
+/** [guid, masterGuid, distYd, angleRad, mapId, flag] — creature_linking FLAG_FOLLOW. */
+type FollowRow = readonly [number, number, number, number, number, number];
+
+export type PackWaypoint = {
+  x: number; y: number; z: number; o: number; waitMs: number; scriptId: number;
+};
+
+export type PatrolFormation = {
+  id: number;
+  map: number;
+  type: number;
+  spread: number;
+  options: number;
+  pathId: number;
+  movementType: number;
+  mirroring: boolean;
+  modelWidth: number;
+  slots: readonly number[];
+};
+
+type PacksFile = {
+  follow: readonly FollowRow[];
+  formations: readonly PatrolFormation[];
+  paths: Readonly<Record<string, readonly PackPathRow[]>>;
+};
+
+const file = packsJson as PacksFile;
+
+export type FollowLink = { guid: number; masterGuid: number; dist: number; angle: number };
+
+const followByMaster = new Map<number, FollowLink[]>();
+const followByGuid = new Map<number, FollowLink>();
+for (const [guid, masterGuid, dist, angle] of file.follow) {
+  const link = { guid, masterGuid, dist, angle };
+  followByGuid.set(guid, link);
+  if (!followByMaster.has(masterGuid)) followByMaster.set(masterGuid, []);
+  followByMaster.get(masterGuid)!.push(link);
+}
+
+const formationByGuid = new Map<number, PatrolFormation>();
+for (const f of file.formations) {
+  for (const g of f.slots) formationByGuid.set(g, f);
+}
+
+/** FLAG_FOLLOW slaves of a patrolling master, by its spawn guid. */
+export function followersOfMaster(masterGuid: number): readonly FollowLink[] {
+  return followByMaster.get(masterGuid | 0) ?? [];
+}
+
+export function followLinkOf(guid: number): FollowLink | undefined {
+  return followByGuid.get(guid | 0);
+}
+
+export function formationOfGuid(guid: number): PatrolFormation | undefined {
+  return formationByGuid.get(guid | 0);
+}
+
+// MT=1/2/4 mover, formation slot or FLAG_FOLLOW slave. Mirroring the frozen inject
+// pose onto one of these fights the stamp (livePullLifecycle.ts:272 floorWorldFromSession).
+export function patrolOwnsOocPose(guid: number, movementType: number): boolean {
+  if (movementType === 2 || movementType === 1 || movementType === LINEAR_WP_MOTION_TYPE) return true;
+  const g = guid | 0;
+  return formationByGuid.has(g) || followByGuid.has(g);
+}
+
+/** Slot 0 owns the path; the rest hold shape offsets. Cite: SpawnGroup.cpp:866-873. */
+export function formationMasterGuid(f: PatrolFormation): number {
+  return f.slots[0] ?? 0;
+}
+
+const pathCache = new Map<number, readonly PackWaypoint[]>();
+
+/** waypoint_path points for a formation, [] when the bake carries none. */
+export function formationPath(pathId: number): readonly PackWaypoint[] {
+  const id = pathId | 0;
+  const hit = pathCache.get(id);
+  if (hit) return hit;
+  const rows = file.paths[String(id)];
+  const out: PackWaypoint[] = (rows ?? []).map(([x, y, z, o, waitMs, scriptId]) => ({
+    x, y, z, o, waitMs, scriptId,
+  }));
+  pathCache.set(id, out);
+  return out;
+}
+
+// LINEAR_WP walks 1..N then back N..1, so the looping pose function sees the path doubled with
+// both endpoints kept once. Cite: WaypointMovementGenerator.cpp:617-645 SwitchToNextNode.
+export function pingPongPath<T>(path: readonly T[]): readonly T[] {
+  if (path.length < 3) return path;
+  const back = path.slice(1, path.length - 1).reverse();
+  return [...path, ...back];
+}
+
+// Slot offset (dist yd, angle rad off the master's facing) for follower `n` of `followers`,
+// 1-based in slot order. Cite: SpawnGroup.cpp:1560-1840 SetFormationSlots.
+export function formationSlotOffset(
+  f: PatrolFormation,
+  n: number,
+  followers: number,
+): { dist: number; angle: number } {
+  const spread = f.spread;
+  const total = Math.max(1, followers);
+  const TAU = Math.PI * 2;
+  switch (f.type) {
+    case FORMATION_SINGLE_FILE:
+      return { dist: spread * n, angle: Math.PI };
+    case FORMATION_SIDE_BY_SIDE:
+      return {
+        dist: spread * (Math.floor((n - 1) / 2) + 1),
+        angle: (n & 1) === 0 ? Math.PI / 2 + Math.PI : Math.PI / 2,
+      };
+    case FORMATION_LIKE_GEESE:
+      return {
+        dist: spread * (Math.floor((n - 1) / 2) + 1),
+        angle: (n & 1) === 0 ? Math.PI + Math.PI / 4 : Math.PI - Math.PI / 4,
+      };
+    case FORMATION_FANNED_OUT_BEHIND:
+      return { dist: spread, angle: Math.PI / 2 + (Math.PI / total) * (n - 1) };
+    case FORMATION_FANNED_OUT_IN_FRONT: {
+      let a = Math.PI + Math.PI / 2 + (Math.PI / total) * (n - 1);
+      if (a > TAU) a -= TAU;
+      return { dist: spread, angle: a };
+    }
+    case FORMATION_CIRCLE_THE_LEADER:
+      return { dist: spread, angle: (TAU / total) * (n - 1) };
+    default:
+      return randomShapeSlot(f, n);
+  }
+}
+
+// SPAWN_GROUP_FORMATION_TYPE_RANDOM. The core then jitters every slot with `frand`
+// (FormationSlotData::AddPositionVariation); a lockstep floor cannot, so the base slot stands.
+function randomShapeSlot(f: PatrolFormation, n: number): { dist: number; angle: number } {
+  const inter = f.modelWidth * 3;
+  const hypAt = (mult: number): number => {
+    const back = f.spread + inter * mult;
+    return Math.sqrt(back * back + inter * inter);
+  };
+  const skew = (mult: number, sign: number): { dist: number; angle: number } => {
+    const hyp = hypAt(mult);
+    const back = f.spread + inter * mult;
+    return { dist: hyp, angle: Math.PI + sign * detAtan2(inter, back) };
+  };
+  switch (n) {
+    case 1: return skew(1, -1);
+    case 2: return skew(1, 1);
+    case 3: return { dist: f.spread + inter * 2, angle: Math.PI };
+    case 4: return { dist: f.spread + inter * 3, angle: Math.PI };
+    case 5: return skew(2, -1);
+    case 6: return skew(2, 1);
+    case 7: return skew(3, -1);
+    case 8: return skew(3, 1);
+    case 9: return { dist: f.spread + inter, angle: Math.PI };
+    default:
+      return {
+        dist: inter * (Math.floor((n - 10) / 2) + 1),
+        angle: (n & 1) === 0 ? Math.PI / 2 + Math.PI : Math.PI / 2,
+      };
+  }
+}
+
+// `dist` yards from the master at `angle` off its facing. Cite: TargetedMovementGenerator.cpp:1001
+// (to + GetAngle()); Object.cpp:2305 GetNearPoint2dAt.
+export function followPose(
+  master: { x: number; y: number; z?: number; o?: number },
+  dist: number,
+  angle: number,
+): { x: number; y: number; z?: number } {
+  const a = (master.o ?? 0) + angle;
+  return {
+    x: master.x + detCos(a) * dist,
+    y: master.y + detSin(a) * dist,
+    ...(master.z != null ? { z: master.z } : {}),
+  };
+}
+
+/** Mirrored slot angle on a linear path's return leg. Cite: SpawnGroup.cpp:1857-1865 GetAngle. */
+export function mirrorAngle(angle: number): number {
+  return Math.PI * 2 - angle;
+}
+
+export function patrolPackCounts(): {
+  follow: number; formations: number; members: number; paths: number;
+} {
+  return {
+    follow: file.follow.length,
+    formations: file.formations.length,
+    members: file.formations.reduce((n, f) => n + f.slots.length, 0),
+    paths: Object.keys(file.paths).length,
+  };
+}