azeroth-shell 0.0.0-stage → 0.1.0

package/src/engine/spells/procs.ts

@@ -0,0 +1,300 @@
+// Proc matching, chance and PPM, unifying the flag filters, the Classic PPM formula and the hidden
+// proc cooldowns. Pure: every roll takes an injected rng, never Math.random.
+
+import type { Rng } from '../core/rng.ts';
+
+/** Subset of SpellMgr.h ProcFlags used by combat event sites. */
+export const PROC_FLAG = {
+  NONE: 0x00000000,
+  // Killing a target that yields XP or honor. Cite: SpellMgr.h:1660 PROC_FLAG_KILL.
+  KILL: 0x00000002,
+  DEAL_MELEE_SWING: 0x00000004,
+  TAKE_MELEE_SWING: 0x00000008,
+  DEAL_MELEE_ABILITY: 0x00000010,
+  TAKE_MELEE_ABILITY: 0x00000020,
+  DEAL_RANGED_ATTACK: 0x00000040,
+  TAKE_RANGED_ATTACK: 0x00000080,
+  DEAL_RANGED_ABILITY: 0x00000100,
+  TAKE_RANGED_ABILITY: 0x00000200,
+  DEAL_HELPFUL_SPELL: 0x00004000,
+  DEAL_HARMFUL_SPELL: 0x00010000,
+  TAKE_HARMFUL_SPELL: 0x00020000,
+  DEAL_HARMFUL_PERIODIC: 0x00040000,
+  TAKE_HARMFUL_PERIODIC: 0x00080000,
+  TAKE_ANY_DAMAGE: 0x00100000,
+} as const;
+
+/** Subset of SpellMgr.h ProcFlagsEx. */
+export const PROC_EX = {
+  NONE: 0x0000000,
+  NORMAL_HIT: 0x0000001,
+  CRITICAL_HIT: 0x0000002,
+  MISS: 0x0000004,
+  RESIST: 0x0000008,
+  DODGE: 0x0000010,
+  PARRY: 0x0000020,
+  BLOCK: 0x0000040,
+} as const;
+
+/** Spell school index → SpellSchoolMask bit (SharedDefines SPELL_SCHOOL_MASK_*). */
+export const SCHOOL_MASK = {
+  NORMAL: 0x01,
+  HOLY: 0x02,
+  FIRE: 0x04,
+  NATURE: 0x08,
+  FROST: 0x10,
+  SHADOW: 0x20,
+  ARCANE: 0x40,
+} as const;
+
+const SCHOOL_NAME_TO_MASK: Record<string, number> = {
+  physical: SCHOOL_MASK.NORMAL,
+  holy: SCHOOL_MASK.HOLY,
+  fire: SCHOOL_MASK.FIRE,
+  nature: SCHOOL_MASK.NATURE,
+  frost: SCHOOL_MASK.FROST,
+  shadow: SCHOOL_MASK.SHADOW,
+  arcane: SCHOOL_MASK.ARCANE,
+};
+
+/** Map Phonecraft School string → SpellSchoolMask bit. */
+export function schoolMaskFromSchool(school: string | undefined | null): number {
+  if (!school) return 0;
+  return SCHOOL_NAME_TO_MASK[school] ?? 0;
+}
+
+/** Context describing a combat event that may trigger procs. */
+export interface ProcEventContext {
+  /** Combined ProcFlags bits for this event (attacker and/or victim side as appropriate). */
+  procFlags: number;
+  /** ProcFlagsEx outcome bits (hit/crit/miss/…). */
+  procEx: number;
+  /** Weapon speed in milliseconds (melee/ranged) for PPM; optional. */
+  weaponSpeedMs?: number;
+  /** Current time (ms) for hidden CD checks. */
+  nowMs: number;
+  // School mask of the *triggering* spell/attack (SPELL_SCHOOL_MASK_*). Melee white hits → NORMAL. Absent →
+  // skip school filter (legacy). Cite: SpellMgr.cpp IsSpellProcEventCanTriggeredBy ~899–909.
+  schoolMask?: number;
+  /** SpellFamilyName of the triggering spell. Melee (no spell) → absent/0. Cite: SpellMgr.cpp ~912. */
+  spellFamilyName?: number;
+  // SpellFamilyFlags of the triggering spell (for family mask filters). Cite: UnitAuraProcHandler.cpp ~634
+  // IsFitToFamilyMask.
+  spellFamilyFlags?: number;
+  outdoors?: boolean;
+}
+
+export interface ProcMatchInput {
+  /** Required ProcFlags bits (any bit match). 0/absent = no flag filter. */
+  procFlags?: number;
+  /** Required ProcEx: if set, (event.procEx & procEx) must be non-zero (or exact policy below). */
+  procEx?: number;
+  chance?: number | null;
+  ppm?: number | null;
+  customChance?: number | null;
+  // The over-100 chance sentinel on an ITEM proc means "use the default weapon formula", which depends
+  // on weapon speed and so cannot be baked. Copied as a literal, 225 of 235 fired on every swing.
+  weaponDefault?: boolean;
+  /** Hidden CD readyAt for the triggered spell. */
+  cooldownReadyAt?: number;
+  cooldownMs?: number;
+  // spell_proc_event.schoolMask — when set, event school must overlap. Melee (no spellInfo) requires NORMAL
+  // school bit. Cite: SpellMgr.cpp ~899–909.
+  schoolMask?: number;
+  /** spell_proc_event.spellFamilyName — when set, must equal event family. */
+  spellFamilyName?: number;
+  // spell_proc_event.spellFamilyMask[3] — when any non-zero, event family flags must fit at least one mask
+  // (bit AND). Cite: UnitAuraProcHandler.cpp ~634.
+  spellFamilyMask?: number[];
+  requiresOutdoors?: boolean;
+}
+
+// True when family flags fit any non-zero mask entry (IsFitToFamilyMask style). Uses Number bit ops;
+// Classic masks in bake are within safe integer range.
+export function spellFamilyMaskFits(
+  spellFamilyFlags: number | undefined,
+  masks: number[] | undefined,
+): boolean {
+  if (!masks || !masks.length) return true;
+  const flags = (spellFamilyFlags ?? 0) | 0;
+  let anyMask = false;
+  for (const m of masks) {
+    const mask = (m ?? 0) | 0;
+    if (!mask) continue;
+    anyMask = true;
+    if ((flags & mask) !== 0) return true;
+  }
+  // All masks zero → no family-mask filter.
+  if (!anyMask) return true;
+  return false;
+}
+
+// True when this proc may roll against the event (flags, ex, school/family, hidden CD). Does not roll
+// chance — caller rolls via tryProc. Cite: SpellMgr.cpp IsSpellProcEventCanTriggeredBy ~843.
+export function procMatchesEvent(proc: ProcMatchInput, ctx: ProcEventContext): boolean {
+  if (proc.cooldownReadyAt != null && proc.cooldownReadyAt > ctx.nowMs) {
+    return false;
+  }
+  if (proc.procFlags != null && proc.procFlags !== 0) {
+    if ((ctx.procFlags & proc.procFlags) === 0) return false;
+  }
+  // A kill event carries no ex bits, school or family: the flag alone decides.
+  // Cite: SpellMgr.cpp:853 "Always trigger for this" (PROC_FLAG_KILL).
+  if ((ctx.procFlags & PROC_FLAG.KILL) !== 0) return true;
+  if (proc.procEx != null && proc.procEx !== 0) {
+    // At least one of the required ex bits must be present on the event.
+    if ((ctx.procEx & proc.procEx) === 0) return false;
+  }
+
+  // School / family filters only when the *proc* carries them (sourced spell_proc_event).
+  if (proc.schoolMask != null && proc.schoolMask !== 0) {
+    // Melee triggers: spellInfo == null → require NORMAL school bit (SpellMgr.cpp ~899–903).
+    const eventSchool = ctx.schoolMask != null && ctx.schoolMask !== 0
+      ? ctx.schoolMask
+      : SCHOOL_MASK.NORMAL;
+    if ((proc.schoolMask & eventSchool) === 0) return false;
+  }
+  if (proc.spellFamilyName != null && proc.spellFamilyName !== 0) {
+    // Family filter only applies when there is a triggering spell (SpellMgr.cpp ~905–913).
+    // Melee white (no family) fails a non-zero family requirement.
+    if ((ctx.spellFamilyName ?? 0) !== proc.spellFamilyName) return false;
+  }
+  if (proc.spellFamilyMask && proc.spellFamilyMask.length) {
+    if (!spellFamilyMaskFits(ctx.spellFamilyFlags, proc.spellFamilyMask)) return false;
+  }
+
+  if (proc.requiresOutdoors && ctx.outdoors === false) return false;
+
+  return true;
+}
+
+// Classic PPM to a per-swing probability: the weapon speed in seconds times the rate over sixty.
+// Cite: Unit.cpp:7717 GetPPMProcChance.
+export function ppmChance(ppm: number, weaponSpeedMs: number): number {
+  if (!(ppm > 0) || !(weaponSpeedMs > 0)) return 0;
+  const speedSec = weaponSpeedMs / 1000;
+  return Math.min(1, (ppm * speedSec) / 60);
+}
+
+// The default weapon-proc chance, which is a function of weapon speed rather than a constant: a 3.3 s
+// weapon gives 5.94% and a 1.5 s dagger 2.7%. Cite: Unit.cpp:7705.
+export function weaponDefaultProcChance(weaponSpeedMs: number): number {
+  if (!(weaponSpeedMs > 0)) return 0;
+  return Math.min(1, (weaponSpeedMs * 1.8) / 1000 / 100);
+}
+
+// Resolve the final proc probability, or null when it cannot be determined. PPM WINS, as it is assigned
+// last in both C++ paths: the old order was backwards, so every PPM proc ignored its rate.
+export function resolveProcProbability(
+  proc: ProcMatchInput,
+  weaponSpeedMs?: number,
+): number | null {
+  // 1. PPM first — it overrides both chance fields in CMaNGOS.
+  if (proc.ppm != null && proc.ppm > 0) {
+    if (weaponSpeedMs == null || weaponSpeedMs <= 0) return null;
+    return ppmChance(proc.ppm, weaponSpeedMs);
+  }
+  if (proc.customChance != null && proc.customChance > 0) {
+    // customChance stored as 0..1 in engine ProcDef; if > 1 treat as percent.
+    return proc.customChance > 1
+      ? Math.min(1, proc.customChance / 100)
+      : Math.min(1, proc.customChance);
+  }
+  if (proc.chance != null && proc.chance > 0) {
+    return Math.min(1, proc.chance);
+  }
+  // 2. The item/enchant `ProcChance > 100` sentinel: derive it from the weapon's speed.
+  if (proc.weaponDefault) {
+    if (weaponSpeedMs == null || weaponSpeedMs <= 0) return null;
+    return weaponDefaultProcChance(weaponSpeedMs);
+  }
+  return null;
+}
+
+// Match + roll. Returns true if the proc fires. RNG is drawn only when probability is resolvable and match
+// passes — preserves seed streams when procs are absent or filtered out pre-roll.
+export function tryProc(
+  proc: ProcMatchInput,
+  ctx: ProcEventContext,
+  rng: Rng,
+): boolean {
+  if (!procMatchesEvent(proc, ctx)) return false;
+  const p = resolveProcProbability(proc, ctx.weaponSpeedMs);
+  if (p == null || p <= 0) return false;
+  return rng.chance(p);
+}
+
+/** readyAt after a successful proc that has a hidden cooldown. */
+export function procCooldownReadyAt(nowMs: number, cooldownMs?: number): number | null {
+  if (cooldownMs == null || cooldownMs <= 0) return null;
+  return nowMs + cooldownMs;
+}
+
+/** Build procEx bits from a simple hit/crit/miss outcome string. */
+export function procExFromOutcome(outcome: 'hit' | 'crit' | 'miss' | 'dodge' | 'parry' | 'block' | 'resist'): number {
+  switch (outcome) {
+    case 'crit': return PROC_EX.CRITICAL_HIT;
+    case 'miss': return PROC_EX.MISS;
+    case 'dodge': return PROC_EX.DODGE;
+    case 'parry': return PROC_EX.PARRY;
+    case 'block': return PROC_EX.BLOCK;
+    case 'resist': return PROC_EX.RESIST;
+    default: return PROC_EX.NORMAL_HIT;
+  }
+}
+
+/** Common attacker-side flags for a landed melee white hit. */
+export function meleeSwingDealFlags(): number {
+  return PROC_FLAG.DEAL_MELEE_SWING;
+}
+
+/** Attacker-side flags for a landed harmful spell (damage). */
+export function harmfulSpellDealFlags(): number {
+  return PROC_FLAG.DEAL_HARMFUL_SPELL;
+}
+
+/** Killer-side flags for a kill that yields XP or honor. Cite: Unit.cpp:1080. */
+export function killDealFlags(): number {
+  return PROC_FLAG.KILL;
+}
+
+/** Attacker-side flags for a melee ability (strike / on-next-swing). */
+export function meleeAbilityDealFlags(): number {
+  return PROC_FLAG.DEAL_MELEE_ABILITY;
+}
+
+/** Defender-side flags for a white melee swing that was dodged/parried/blocked. */
+export function meleeSwingTakeFlags(): number {
+  return PROC_FLAG.TAKE_MELEE_SWING;
+}
+
+/** Defender-side flags for a melee ability outcome. */
+export function meleeAbilityTakeFlags(): number {
+  return PROC_FLAG.TAKE_MELEE_ABILITY;
+}
+
+/** Defender-side flags for a harmful spell land-fail (full resist). */
+export function harmfulSpellTakeFlags(): number {
+  return PROC_FLAG.TAKE_HARMFUL_SPELL;
+}
+
+// Which combat event a proc site is reporting. One hint per PROC_FLAG_DEAL_* family — the ranged pair used
+// to have no hint at all, so bow and wand hits borrowed a melee/spell one.
+export type ProcFlagsHint =
+  | 'melee_swing'
+  | 'melee_ability'
+  | 'ranged_attack'
+  | 'ranged_ability'
+  | 'spell'
+  | 'kill';
+
+// The attacker-side flags for a landed ranged white. Both ranged bits were declared and emitted by
+// nothing, so every ranged hit was tagged melee or harmful-spell and matched the wrong auras.
+export function rangedAttackDealFlags(): number {
+  return PROC_FLAG.DEAL_RANGED_ATTACK;
+}
+
+/** Attacker-side flags for a ranged ABILITY (Aimed Shot / Multi-Shot / Arcane Shot). */
+export function rangedAbilityDealFlags(): number {
+  return PROC_FLAG.DEAL_RANGED_ABILITY;
+}

package/src/engine/spells/recovery.ts

@@ -0,0 +1,203 @@
+// Cooldown categories plus the global cooldown and recovery helpers, extracted so every cast site
+// shares one definition. Pure: no DOM, no Math.random, no I/O.
+
+import type { SpellRole } from '../../data/schema.ts';
+import { SPELL_ATTR } from './spellAttributes.ts';
+
+/** Minimal spell fields for recovery helpers (avoids brittle Pick on optional keys). */
+export interface RecoverySpellFields {
+  id?: number;
+  cooldownMs?: number;
+  categoryRecoveryMs?: number;
+  category?: number;
+  onNextSwing?: boolean;
+  gcdMs?: number;
+  role?: SpellRole | null;
+  comboPointsGenerated?: number;
+  requiresComboPoints?: boolean;
+  /** SpellEntry.StartRecoveryCategory — 133 is the global GCD, the only hasted bucket. */
+  gcdCategory?: number;
+  /** SpellEntry.Attributes — read for IS_ABILITY / USES_RANGED_SLOT. */
+  attributes?: number;
+  /** SpellEntry.DmgClass — melee/ranged are never hasted. */
+  dmgClass?: number;
+}
+
+// The effective recovery duration: the larger of the spell's own and its category's. With no category
+// recovery baked, the personal one alone is returned.
+export function getSpellRecoveryTime(spell: RecoverySpellFields): number {
+  const personal = (spell.cooldownMs ?? 0) | 0;
+  const category = (spell.categoryRecoveryMs ?? 0) | 0;
+  return personal > category ? personal : category;
+}
+
+// The duration for the spell's PERSONAL cooldown. With no real category but a category recovery time —
+// common on creature spells — the larger value folds into the personal timer so the cooldown survives.
+export function personalCooldownMs(spell: RecoverySpellFields): number {
+  const personal = (spell.cooldownMs ?? 0) | 0;
+  if (spell.category != null && spell.category !== 0) return personal;
+  const catRec = (spell.categoryRecoveryMs ?? 0) | 0;
+  return personal > catRec ? personal : catRec;
+}
+
+// The duration for the SHARED category timer when the spell has a category: the category recovery when
+// set, else the personal one. No category means no category timer.
+export function categoryCooldownMs(spell: RecoverySpellFields): number {
+  if (spell.category == null || spell.category === 0) return 0;
+  if (spell.categoryRecoveryMs != null && spell.categoryRecoveryMs > 0) {
+    return spell.categoryRecoveryMs;
+  }
+  return (spell.cooldownMs ?? 0) | 0;
+}
+
+/** SpellMgr.h IsNextMeleeSwingSpell — Phonecraft uses baked onNextSwing. */
+export function isNextMeleeSwingSpell(spell: RecoverySpellFields): boolean {
+  return !!spell.onNextSwing || (((spell.attributes ?? 0) & (SPELL_ATTR.ON_NEXT_SWING_NO_DAMAGE | SPELL_ATTR.ON_NEXT_SWING)) !== 0);
+}
+
+/** SPELL_ATTR_USES_RANGED_SLOT. Cite: SpellDefines.h SpellAttributes. */
+const SPELL_ATTR_USES_RANGED_SLOT = 0x00000002;
+/** SPELL_ATTR_IS_ABILITY. Cite: SpellDefines.h SpellAttributes. */
+const SPELL_ATTR_IS_ABILITY = 0x00000010;
+/** SharedDefines SpellDmgClass. */
+const SPELL_DAMAGE_CLASS_MELEE = 2;
+const SPELL_DAMAGE_CLASS_RANGED = 3;
+/** The one global-cooldown bucket. Cite: Player.cpp:20080. */
+const GCD_CATEGORY_GLOBAL = 133;
+
+// Whether the spell incurs the global cooldown. The recovery-start field IS the rule — a zero row is
+// off-GCD. A role fallback here synthesized a 1500 ms GCD onto 658 rows, Auto Shot among them.
+export function spellIncursGcd(spell: RecoverySpellFields): boolean {
+  if (spell.onNextSwing) return false;
+  return ((spell.gcdMs ?? 0) | 0) > 0;
+}
+
+/** GCD duration (ms) for this cast — StartRecoveryTime, or 0 when off-GCD. */
+export function getGcdMs(spell: RecoverySpellFields): number {
+  return spellIncursGcd(spell) ? ((spell.gcdMs ?? 0) | 0) : 0;
+}
+
+// Whether cast haste shortens this GCD. Only the player path has a haste branch and it is narrow: the
+// global category, a 1500 ms base, and neither a weapon damage class nor an ability.
+export function gcdIsHasted(spell: RecoverySpellFields, playerControlled: boolean): boolean {
+  if (!playerControlled) return false;
+  if ((spell.gcdCategory ?? 0) !== GCD_CATEGORY_GLOBAL) return false;
+  if (((spell.gcdMs ?? 0) | 0) !== 1500) return false;
+  const dc = spell.dmgClass ?? 0;
+  if (dc === SPELL_DAMAGE_CLASS_MELEE || dc === SPELL_DAMAGE_CLASS_RANGED) return false;
+  const attrs = (spell.attributes ?? 0) | 0;
+  if ((attrs & SPELL_ATTR_USES_RANGED_SLOT) !== 0) return false;
+  return (attrs & SPELL_ATTR_IS_ABILITY) === 0;
+}
+
+// True when personal or category recovery still blocks the cast. Mirrors Fighter onCooldown(cooldowns +
+// categoryCooldowns).
+function isOnCooldown(
+  spell: RecoverySpellFields,
+  nowMs: number,
+  personalReadyAt: number,
+  categoryReadyAt: number,
+): boolean {
+  if (personalReadyAt > nowMs) return true;
+  if (spell.category != null && categoryReadyAt > nowMs) return true;
+  return false;
+}
+
+// COOLDOWN_ON_EVENT, on 72 playable rows: the cast installs a PERMANENT entry and the real timer starts
+// when the aura fades or the summon dies. Cite: Spell.cpp:3414; Player.cpp:20163-20167.
+export function cooldownStartsOnAuraFade(spell: RecoverySpellFields): boolean {
+  return ((spell.attributes ?? 0) & 0x02000000) !== 0;
+}
+
+// The ready-at an armed-but-unstarted cooldown holds. Infinity IS the permanent entry: every
+// ready check already treats it as not ready. Cite: Player.cpp:20152 IsPermanent.
+export const PERMANENT_COOLDOWN_READY_AT = Number.POSITIVE_INFINITY;
+
+// Compute readyAt timestamps after a successful cast (not on-next-swing arm). Personal and category timers
+// are independent durations.
+export function recoveryReadyAts(
+  spell: RecoverySpellFields,
+  nowMs: number,
+): { personalReadyAt: number | null; categoryReadyAt: number | null; category: number | null } {
+  const p = personalCooldownMs(spell);
+  const c = categoryCooldownMs(spell);
+  return {
+    personalReadyAt: p > 0 ? nowMs + p : null,
+    categoryReadyAt: c > 0 && spell.category != null ? nowMs + c : null,
+    category: spell.category != null && c > 0 ? spell.category : null,
+  };
+}
+
+// World-clock readyAt map (epoch ms) → the "remaining ms at t=0" form a session seeds with. Expired rows
+// drop; an empty result returns undefined so callers can skip the field.
+export function sessionSeedFromWorldCooldowns(
+  store: Record<number, number> | undefined,
+  now: number,
+): Record<number, number> | undefined {
+  if (!store) return undefined;
+  let out: Record<number, number> | undefined;
+  // No `| 0` anywhere on these: an epoch stamp is ~1.8e12 and int32 truncation wraps it.
+  for (const [k, readyAt] of Object.entries(store)) {
+    const rem = Number(readyAt) - now;
+    if (rem > 0) (out ??= {})[Number(k)] = rem;
+  }
+  return out;
+}
+
+// Session remainings folded into a world-clock ready-at map, merged onto what the unit carried and
+// pruned of anything expired. Undefined when nothing is on cooldown, so the caller can drop the field.
+export function worldCooldownsFromSessionSnapshot(
+  prev: Record<number, number> | undefined,
+  remaining: Record<number, number>,
+  now: number,
+): Record<number, number> | undefined {
+  let out: Record<number, number> | undefined;
+  for (const [k, readyAt] of Object.entries(prev ?? {})) {
+    const at = Number(readyAt);
+    if (at > now) (out ??= {})[Number(k)] = at;
+  }
+  for (const [k, rem] of Object.entries(remaining)) {
+    const r = Number(rem);
+    if (r > 0) (out ??= {})[Number(k)] = now + r;
+  }
+  return out;
+}
+
+/** Scope for scripted cooldown resets (Cold Snap / Preparation / Readiness). */
+export type ResetCooldownScope = 'frost' | 'rogue' | 'hunter';
+
+// Finish the world cooldowns matching a scripted reset's scope, mutating the maps in place. The
+// resetter's OWN cooldown is never cleared — the cast site starts it after the effects apply.
+export function applyResetCooldownsWorld(
+  scope: ResetCooldownScope,
+  selfSpellId: number,
+  spellCooldowns: Record<number, number> | undefined,
+  categoryCooldowns: Record<number, number> | undefined,
+  knownSpellIds: readonly number[],
+  lookup: (id: number) => { school?: string; category?: number; cooldownMs?: number; categoryRecoveryMs?: number } | undefined,
+): void {
+  if (spellCooldowns) {
+    for (const idStr of Object.keys(spellCooldowns)) {
+      const id = Number(idStr);
+      if (id === selfSpellId) continue;
+      const other = lookup(id);
+      if (!other) continue;
+      if (scope === 'frost' && (other.school !== 'frost' || getSpellRecoveryTime(other) === 0)) continue;
+      // rogue / hunter: clear other ability CDs (known kit is class-scoped).
+      delete spellCooldowns[id];
+      if (other.category != null && categoryCooldowns) {
+        delete categoryCooldowns[other.category];
+      }
+    }
+  }
+  // Category-only recovery rows for matching known spells.
+  if (categoryCooldowns) {
+    for (const knownId of knownSpellIds) {
+      if (knownId === selfSpellId) continue;
+      const other = lookup(knownId);
+      if (!other || other.category == null) continue;
+      if (scope === 'frost' && (other.school !== 'frost' || getSpellRecoveryTime(other) === 0)) continue;
+      delete categoryCooldowns[other.category];
+    }
+  }
+}

package/src/engine/spells/scriptTargetDest.ts

@@ -0,0 +1,76 @@
+// The fixed room point a script-targeted effect resolves to instead of the caster's feet: the C++
+// picks the NEAREST listed spawn and sets it as the destination. Scoped to living-creature rows.
+
+import { dungeonSpawnsForMap } from '../../data/dungeonSpawns.ts';
+import { detHypot } from '../core/detMath.ts';
+import { scriptTargetRowsFor, SPELL_TARGET_TYPE_CREATURE } from './scriptTargets.ts';
+import { SPELL_RADIUS_SENTINEL_YD, spellRadiusYd } from './spellRadius.ts';
+
+/** Cite: SpellTargetDefines.h:70. */
+export const TARGET_LOCATION_SCRIPT_NEAR_CASTER = 46;
+
+/** Cite: ObjectDefines.h:39 DEFAULT_VISIBILITY_INSTANCE = 170.0f. */
+const DEFAULT_VISIBILITY_INSTANCE_YD = 170;
+
+/** Cite: Spell.cpp:2650-2651 — the 50000 sentinel is trimmed to 200 for an entry search. */
+const SCRIPT_TARGET_RADIUS_CAP_YD = 200;
+
+export type ScriptTargetDest = {
+  x: number;
+  y: number;
+  z?: number;
+  // The effect's OWN radius, which is what EffectSummonWild scatters the extra bodies over — not the
+  // (possibly rewritten) search radius. Cite: SpellEffects.cpp:2764.
+  scatterYd: number;
+  /** Spawn guid the dest came from — the evidence line for a probe or a log. */
+  guid: number;
+};
+
+/** True when this rawEffect resolves its destination through CheckScriptTargeting. */
+export function effectUsesScriptDest(raw: { targetA?: number; targetB?: number }): boolean {
+  return (raw.targetA ?? 0) === TARGET_LOCATION_SCRIPT_NEAR_CASTER
+    || (raw.targetB ?? 0) === TARGET_LOCATION_SCRIPT_NEAR_CASTER;
+}
+
+// The search bound for the entry lookup: the 50000 sentinel becomes 200 and a zero radius the map's
+// visibility distance. Both exceed any room. Cite: Spell.cpp:2650-2654.
+export function scriptTargetSearchRadiusYd(effectRadiusYd: number): number {
+  if (effectRadiusYd === SPELL_RADIUS_SENTINEL_YD) return SCRIPT_TARGET_RADIUS_CAP_YD;
+  if (!(effectRadiusYd > 0)) return DEFAULT_VISIBILITY_INSTANCE_YD;
+  return effectRadiusYd;
+}
+
+// The nearest listed script-target spawn to a point, as a world position. Null on any of the C++'s own
+// failure paths, and `near` is required because "nearest" IS the rule — ZG has six such spawns.
+export function scriptTargetDestFor(opts: {
+  spellId: number;
+  radiusIndex: number;
+  mapId?: number;
+  near: { x: number; y: number };
+}): ScriptTargetDest | null {
+  const entries = new Set<number>();
+  for (const row of scriptTargetRowsFor(opts.spellId)) {
+    if (row.t === SPELL_TARGET_TYPE_CREATURE) entries.add(row.e | 0);
+  }
+  if (entries.size === 0) return null;
+  if (opts.mapId == null) return null;
+
+  const scatterYd = spellRadiusYd(opts.radiusIndex);
+  const searchYd = scriptTargetSearchRadiusYd(scatterYd);
+  const near = opts.near;
+
+  let best: { x: number; y: number; z?: number; guid: number } | null = null;
+  let bestDist = Infinity;
+  for (const s of dungeonSpawnsForMap(opts.mapId)) {
+    if (!entries.has(s.entry | 0)) continue;
+    const d = detHypot(s.x - near.x, s.y - near.y);
+    if (d > searchYd) continue;
+    // Guid breaks an exact tie so two peers pick the same spawn.
+    if (d < bestDist || (d === bestDist && best != null && s.guid < best.guid)) {
+      best = { x: s.x, y: s.y, z: s.z, guid: s.guid };
+      bestDist = d;
+    }
+  }
+  if (!best) return null;
+  return { ...best, scatterYd };
+}

package/src/engine/spells/scriptTargets.ts

@@ -0,0 +1,85 @@
+// `spell_script_target`, the gate that makes a script-targeted cast possible or refuses it. With no
+// gate, Corpse Explosion was cast at the party from the first second — 17,895 of 32,513 damage.
+import scriptTargetsJson from '../../data/spell-script-targets.json' with { type: 'json' };
+
+/** Cite: SpellMgr.h:1771-1776 `enum SpellScriptTargetType`. */
+export const SPELL_TARGET_TYPE_GAMEOBJECT = 0;
+export const SPELL_TARGET_TYPE_CREATURE = 1;
+export const SPELL_TARGET_TYPE_DEAD = 2;
+
+/** Cite: SpellTargetDefines.h:62,66,70 — the three modes CheckScriptTargeting owns. */
+const SCRIPT_TARGET_MODES = new Set([38, 40, 46]);
+
+export type ScriptTargetRow = { t: number; e: number; m?: number };
+
+const ROWS = scriptTargetsJson as Record<string, ScriptTargetRow[]>;
+
+/** `spell_script_target` rows for a spell; empty when the table has none. */
+export function scriptTargetRowsFor(spellId: number): readonly ScriptTargetRow[] {
+  return ROWS[String(spellId | 0)] ?? [];
+}
+
+/** Living creature entries listed as type-1 script targets for this spell. */
+export function scriptTargetCreatureEntries(spellId: number): number[] {
+  const out: number[] = [];
+  for (const row of scriptTargetRowsFor(spellId)) {
+    if (row.t !== SPELL_TARGET_TYPE_CREATURE) continue;
+    if (!out.includes(row.e | 0)) out.push(row.e | 0);
+  }
+  return out;
+}
+
+// How a self-cast picks its script targets for this spell's raw effects.
+// Cite: SpellTargets.cpp:40 the source-location AoE; :71 the near-caster unit.
+export function scriptTargetPickMode(
+  raw: readonly { targetA?: number; targetB?: number }[] | undefined,
+): 'near' | 'aoe' | 'none' {
+  if (!raw?.length) return 'none';
+  let aoe = false;
+  for (const e of raw) {
+    const a = e.targetA ?? 0;
+    const b = e.targetB ?? 0;
+    if (a === 38 || b === 38) return 'near';
+    if (a === 7 || b === 7 || a === 8 || b === 8) aoe = true;
+  }
+  return aoe ? 'aoe' : 'none';
+}
+
+/** True when any effect of this spell resolves through CheckScriptTargeting. */
+export function spellUsesScriptTarget(
+  raw: readonly { targetA?: number; targetB?: number }[] | undefined,
+): boolean {
+  if (!raw?.length) return false;
+  for (const e of raw) {
+    if (SCRIPT_TARGET_MODES.has(e.targetA ?? 0)) return true;
+    if (SCRIPT_TARGET_MODES.has(e.targetB ?? 0)) return true;
+  }
+  return false;
+}
+
+// Refuse a script-targeted cast whose rows are all corpse-type when no matching corpse is present.
+// SCOPED to that type: the living and gameobject rows name world objects a session does not model.
+export function refuseForMissingCorpse(
+  spellId: number,
+  raw: readonly { targetA?: number; targetB?: number }[] | undefined,
+  hasCorpse: (creatureEntry: number) => boolean,
+): boolean {
+  if (!spellUsesScriptTarget(raw)) return false;
+  const rows = scriptTargetRowsFor(spellId);
+  if (!rows.length) return false;
+  const dead = rows.filter((r) => r.t === SPELL_TARGET_TYPE_DEAD);
+  if (!dead.length || dead.length !== rows.length) return false;
+  return !dead.some((r) => hasCorpse(r.e));
+}
+
+// Living-creature entries a BARE use can never satisfy: with no target the C++ finds nothing and fails
+// before the item is spent. 32 of 39 such items succeeded on a bag click, destroying 12 quest items.
+export function bareUseRefusedCreatureEntries(
+  spellId: number,
+  raw: readonly { targetA?: number; targetB?: number }[] | undefined,
+): number[] {
+  if (!raw?.length) return [];
+  const nearUnit = raw.some((e) => (e.targetA ?? 0) === 38 || (e.targetB ?? 0) === 38);
+  if (!nearUnit) return [];
+  return scriptTargetCreatureEntries(spellId);
+}