azeroth-shell 0.0.0-stage → 0.1.1

package/src/engine/spells/interpreter/registry/packs/si4-script-generic-a.ts

@@ -0,0 +1,114 @@
+// EffectScriptEffect SPELLFAMILY_GENERIC ids 17512–24195. Cite: SpellEffects.cpp:3729–3801.
+
+import type { RegistryHandler, RegistryPack } from '../types.ts';
+import {
+  JUBLING_COOLDOWN_SPELL_ID,
+  JUBLING_COOLDOWN_TRIGGER_SPELL_ID,
+  ONYXIA_SCALE_CLOAK_SPELL_ID,
+  PICCOLO_OF_THE_FLAMING_FIRE_SPELL_ID,
+  SHADOW_FLAME_DOT_AMOUNT,
+  SHADOW_FLAME_DOT_DURATION_MS,
+  SHADOW_FLAME_DOT_SPELL_ID,
+  SHADOW_FLAME_DOT_TICK_MS,
+  shadowFlameAppliesDot,
+} from '../../../cmangos-special-cases.ts';
+import {
+  GROMS_TRIBUTE_BY_RACE,
+  GROMS_TRIBUTE_SPELL_ID,
+  UTHERS_TRIBUTE_BY_RACE,
+  UTHERS_TRIBUTE_SPELL_ID,
+} from '../../../cmangos-special-cases-s18.ts';
+import {
+  BANISH_EXILE_BURNING_SPELL_ID,
+  BANISH_EXILE_CRESTING_SPELL_ID,
+  BANISH_EXILE_THUNDERING_SPELL_ID,
+} from '../../../cmangos-special-cases.ts';
+import { CONTROL_CONSOLE_REMOVE_TARGET_SPELL } from '../../handlers/shared.ts';
+
+/** Onyxia Shadow Flame SCRIPT siblings sharing the 22682 cast. Cite: SpellEffects.cpp:3738–3761. */
+export const SHADOW_FLAME_SCRIPT_SPELL_IDS: readonly number[] = [
+  22972, 22975, 22976, 22977, 22978, 22979, 22980, 22981, 22982, 22983, 22984, 22985,
+];
+
+// Banish Exile — unitTarget casts 3617 to trigger dispel. Cite: item_scripts.cpp:136-139.
+const handleBanishExile: RegistryHandler = (state) => {
+  // DoScriptText(-1010004) flavor emitted as no-op until text surfaces exist.
+  state.intents.push({
+    kind: 'trigger_spell_as_unit_target',
+    spellId: CONTROL_CONSOLE_REMOVE_TARGET_SPELL,
+  });
+  state.effects.push({ kind: 'trigger_spell', spellId: CONTROL_CONSOLE_REMOVE_TARGET_SPELL });
+  return true;
+};
+
+// Piccolo of the Flaming Fire — HandleEmoteCommand(EMOTE_STATE_DANCE) on player. Cite:
+// SpellEffects.cpp:3729–3736.
+const handlePiccoloOfTheFlamingFire: RegistryHandler = (state, _raw, _slot) => {
+  state.effects.push({
+    kind: 'script_handled_noop',
+    spellId: PICCOLO_OF_THE_FLAMING_FIRE_SPELL_ID,
+  } as never);
+  return true;
+};
+
+// Shadow Flame SCRIPT_EFFECT — CastSpell(22682) unless Onyxia Scale Cloak 22683. Cite:
+// SpellEffects.cpp:3738–3761 (same body as 22539).
+const handleShadowFlameScript: RegistryHandler = (state, _raw, _slot) => {
+  const auras = state.ctx.targetAuras ?? [];
+  const hasCloak = auras.some((a) => (a.spellId | 0) === ONYXIA_SCALE_CLOAK_SPELL_ID);
+  if (!shadowFlameAppliesDot(hasCloak)) return true;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId: SHADOW_FLAME_DOT_SPELL_ID });
+  state.effects.push({
+    kind: 'dot',
+    school: 'shadow',
+    min: SHADOW_FLAME_DOT_AMOUNT,
+    max: SHADOW_FLAME_DOT_AMOUNT,
+    tickMs: SHADOW_FLAME_DOT_TICK_MS,
+    durationMs: SHADOW_FLAME_DOT_DURATION_MS,
+  });
+  return true;
+};
+
+// Jubling Cooldown — CastSpell(23852). Cite: SpellEffects.cpp:3763–3766.
+const handleJublingCooldown: RegistryHandler = (state, _raw, _slot) => {
+  state.intents.push({ kind: 'cast_triggered_spell', spellId: JUBLING_COOLDOWN_TRIGGER_SPELL_ID });
+  state.effects.push({ kind: 'trigger_spell', spellId: JUBLING_COOLDOWN_TRIGGER_SPELL_ID });
+  return true;
+};
+
+// Uther's / Grom's Tribute — race → holiday buff. Cite: SpellEffects.cpp:3768–3801.
+const handleTribute: RegistryHandler = (state, _raw, _slot) => {
+  const race = (state.ctx as { casterRace?: number }).casterRace ?? 0;
+  const id = state.spell.id | 0;
+  const spellId =
+    id === UTHERS_TRIBUTE_SPELL_ID
+      ? (UTHERS_TRIBUTE_BY_RACE[race] ?? 0)
+      : id === GROMS_TRIBUTE_SPELL_ID
+        ? (GROMS_TRIBUTE_BY_RACE[race] ?? 0)
+        : 0;
+  if (spellId) {
+    state.intents.push({ kind: 'cast_triggered_spell', spellId });
+    state.effects.push({ kind: 'trigger_spell', spellId });
+  } else {
+    state.effects.push({ kind: 'script_handled_noop', spellId: id } as never);
+  }
+  return true;
+};
+
+const script: Record<number, RegistryHandler> = {
+  [BANISH_EXILE_BURNING_SPELL_ID]: handleBanishExile,
+  [BANISH_EXILE_CRESTING_SPELL_ID]: handleBanishExile,
+  [BANISH_EXILE_THUNDERING_SPELL_ID]: handleBanishExile,
+  [PICCOLO_OF_THE_FLAMING_FIRE_SPELL_ID]: handlePiccoloOfTheFlamingFire,
+  [JUBLING_COOLDOWN_SPELL_ID]: handleJublingCooldown,
+  [UTHERS_TRIBUTE_SPELL_ID]: handleTribute,
+  [GROMS_TRIBUTE_SPELL_ID]: handleTribute,
+};
+for (const id of SHADOW_FLAME_SCRIPT_SPELL_IDS) {
+  script[id] = handleShadowFlameScript;
+}
+
+export const si4ScriptGenericAPack: RegistryPack = {
+  id: 'si4-script-generic-a',
+  script,
+};

package/src/engine/spells/interpreter/registry/packs/si4-script-generic-b.ts

@@ -0,0 +1,249 @@
+// EffectScriptEffect SPELLFAMILY_GENERIC ids 24714–26264. Cite: SpellEffects.cpp:3812–3987.
+
+import type { RegistryHandler, RegistryPack } from '../types.ts';
+import {
+  GHOST_COSTUME_FEMALE_SPELL_ID,
+  GHOST_COSTUME_MALE_SPELL_ID,
+  GHOST_COSTUME_SPELL_ID,
+  HALLOWS_END_TRICK_SPELL_ID,
+  LEPER_GNOME_COSTUME_FEMALE_SPELL_ID,
+  LEPER_GNOME_COSTUME_MALE_SPELL_ID,
+  LEPER_GNOME_COSTUME_SPELL_ID,
+  NINJA_COSTUME_FEMALE_SPELL_ID,
+  NINJA_COSTUME_MALE_SPELL_ID,
+  NINJA_COSTUME_SPELL_ID,
+  PIRATE_COSTUME_FEMALE_SPELL_ID,
+  PIRATE_COSTUME_MALE_SPELL_ID,
+  PIRATE_COSTUME_SPELL_ID,
+  pickHallowsEndTrickOutcome,
+  RANDOM_COSTUME_SPELL_ID,
+  SUMMON_RC_TANK_SPELL_ID,
+  SUMMON_RC_TANK_SUMMON_SPELL_ID,
+} from '../../../cmangos-special-cases-s18.ts';
+import {
+  DRAIN_MANA_ERADICATOR_TRIGGER_SPELL_ID,
+  DRAIN_MANA_NULLIFIER_TRIGGER_SPELL_ID,
+  MISTLETOE_CHEER_SPELL_ID,
+  MISTLETOE_RANDOM_OUTCOMES,
+  MISTLETOE_RANDOM_SPELL_ID,
+} from '../../../cmangos-special-cases-s19.ts';
+
+/** Cannon Fire SCRIPT → unitTarget casts Magic Wings. Cite: SpellEffects.cpp:3900–3906. */
+export const CANNON_FIRE_SPELL_ID = 24731;
+/** Magic Wings — strip Darkmoon cannon root. Cite: SpellEffects.cpp:3917–3923. */
+export const MAGIC_WINGS_SPELL_ID = 24742;
+/** Darkmoon Faire Cannon root aura. Cite: SpellEffects.cpp:3921. */
+export const DARKMOON_CANNON_ROOT_AURA_SPELL_ID = 24754;
+/** Trick or Treat. Cite: SpellEffects.cpp:3925–3935. */
+export const TRICK_OR_TREAT_SPELL_ID = 24751;
+/** Tricked or Treated mark. Cite: SpellEffects.cpp:3931. */
+export const TRICKED_OR_TREATED_SPELL_ID = 24755;
+/** Treat branch of Trick or Treat. Cite: SpellEffects.cpp:3934. */
+export const TREAT_SPELL_ID = 24715;
+/** Drain Mana SCRIPT siblings that cast 26639. Cite: SpellEffects.cpp:3945–3949. */
+export const DRAIN_MANA_FEEDBACK_SPELL_ID = 26639;
+/** Obsidian Destroyer Drain Mana parent. Cite: SpellEffects.cpp:3957–3961. */
+export const OBSIDIAN_DESTROYER_DRAIN_MANA_SPELL_ID = 25754;
+/** Despawn SCRIPT — ForcedDespawn creature target. Cite: SpellEffects.cpp:3981–3987. */
+export const DESPAWN_SCRIPT_SPELL_ID = 26264;
+
+/** Skeleton / bat / wisp Random Costume outcomes. Cite: SpellEffects.cpp:3884–3893. */
+const SKELETON_COSTUME_SPELL_ID = 24723;
+const BAT_COSTUME_SPELL_ID = 24732;
+const WISP_COSTUME_SPELL_ID = 24740;
+
+function roll01(state: { ctx: { rng?: () => number } }): number {
+  return state.ctx.rng ? state.ctx.rng() : 0;
+}
+
+// Random Costume urand(0,6). Cite: SpellEffects.cpp:3872–3894.
+function pickRandomCostumeSpellId(roll0to6: number, isMale: boolean): number {
+  switch (roll0to6 | 0) {
+    case 0:
+      return isMale ? PIRATE_COSTUME_MALE_SPELL_ID : PIRATE_COSTUME_FEMALE_SPELL_ID;
+    case 1:
+      return isMale ? NINJA_COSTUME_MALE_SPELL_ID : NINJA_COSTUME_FEMALE_SPELL_ID;
+    case 2:
+      return isMale ? LEPER_GNOME_COSTUME_MALE_SPELL_ID : LEPER_GNOME_COSTUME_FEMALE_SPELL_ID;
+    case 3:
+      return SKELETON_COSTUME_SPELL_ID;
+    case 4:
+      return BAT_COSTUME_SPELL_ID;
+    case 5:
+      return isMale ? GHOST_COSTUME_MALE_SPELL_ID : GHOST_COSTUME_FEMALE_SPELL_ID;
+    case 6:
+      return WISP_COSTUME_SPELL_ID;
+    default:
+      return SKELETON_COSTUME_SPELL_ID;
+  }
+}
+
+// Trick — player caster urand of 13 morphs. Cite: SpellEffects.cpp:3812–3836.
+const handleHallowsEndTrick: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.casterIsPlayer === false) return true;
+  const spellId = pickHallowsEndTrickOutcome(roll01(state));
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Pirate Costume — gender → 24708/24709. Cite: SpellEffects.cpp:3838–3845.
+const handlePirateCostume: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const male = state.ctx.unitTargetGender !== 1;
+  const spellId = male ? PIRATE_COSTUME_MALE_SPELL_ID : PIRATE_COSTUME_FEMALE_SPELL_ID;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Ninja Costume — gender → 24711/24710. Cite: SpellEffects.cpp:3847–3854.
+const handleNinjaCostume: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const male = state.ctx.unitTargetGender !== 1;
+  const spellId = male ? NINJA_COSTUME_MALE_SPELL_ID : NINJA_COSTUME_FEMALE_SPELL_ID;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Leper Gnome Costume — gender → 24712/24713. Cite: SpellEffects.cpp:3856–3863.
+const handleLeperGnomeCostume: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const male = state.ctx.unitTargetGender !== 1;
+  const spellId = male ? LEPER_GNOME_COSTUME_MALE_SPELL_ID : LEPER_GNOME_COSTUME_FEMALE_SPELL_ID;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Random Costume — urand(0,6) table. Cite: SpellEffects.cpp:3865–3898.
+const handleRandomCostume: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const roll = state.ctx.rng ? Math.floor(state.ctx.rng() * 7) : 0;
+  const male = state.ctx.unitTargetGender !== 1;
+  const spellId = pickRandomCostumeSpellId(roll, male);
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Cannon Fire — unitTarget casts 24742 on caster. Cite: SpellEffects.cpp:3900–3906.
+const handleCannonFire: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.casterIsPlayer === false) return true;
+  state.intents.push({ kind: 'trigger_spell_as_unit_target', spellId: MAGIC_WINGS_SPELL_ID });
+  state.effects.push({ kind: 'trigger_spell', spellId: MAGIC_WINGS_SPELL_ID });
+  return true;
+};
+
+// Ghost Costume — gender → 24735/24736. Cite: SpellEffects.cpp:3908–3915.
+const handleGhostCostume: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const male = state.ctx.unitTargetGender !== 1;
+  const spellId = male ? GHOST_COSTUME_MALE_SPELL_ID : GHOST_COSTUME_FEMALE_SPELL_ID;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Magic Wings — RemoveAurasDueToSpell(24754). Cite: SpellEffects.cpp:3917–3923.
+const handleMagicWings: RegistryHandler = (state, _raw, _slot) => {
+  state.intents.push({
+    kind: 'consume_aura',
+    spellId: DARKMOON_CANNON_ROOT_AURA_SPELL_ID,
+    spellFamilyName: 0,
+    spellFamilyFlags: 0,
+    auraType: 0,
+  });
+  return true;
+};
+
+// Trick or Treat — 24755 + 50% 24714/24715 from unitTarget. Cite: SpellEffects.cpp:3925–3935.
+const handleTrickOrTreat: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  state.intents.push({ kind: 'trigger_spell_as_unit_target', spellId: TRICKED_OR_TREATED_SPELL_ID });
+  state.effects.push({ kind: 'trigger_spell', spellId: TRICKED_OR_TREATED_SPELL_ID });
+  // roll_chance_i(50) → rng [0,1) < 0.5. Cite: SpellEffects.cpp:3934.
+  const spellId = roll01(state) < 0.5 ? HALLOWS_END_TRICK_SPELL_ID : TREAT_SPELL_ID;
+  state.intents.push({ kind: 'trigger_spell_as_unit_target', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Summon RC Tank — CastSpell(24934). Cite: SpellEffects.cpp:3937–3943.
+const handleSummonRcTank: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.casterIsPlayer === false) return true;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId: SUMMON_RC_TANK_SUMMON_SPELL_ID });
+  state.effects.push({ kind: 'trigger_spell', spellId: SUMMON_RC_TANK_SUMMON_SPELL_ID });
+  return true;
+};
+
+// Drain Mana 25671/25755 — unitTarget casts 26639 on caster. Cite: SpellEffects.cpp:3945–3949.
+const handleDrainManaFeedback: RegistryHandler = (state, _raw, _slot) => {
+  state.intents.push({ kind: 'trigger_spell_as_unit_target', spellId: DRAIN_MANA_FEEDBACK_SPELL_ID });
+  state.effects.push({ kind: 'trigger_spell', spellId: DRAIN_MANA_FEEDBACK_SPELL_ID });
+  return true;
+};
+
+// Obsidian Destroyer Drain Mana — CastSpell(25755). Cite: SpellEffects.cpp:3957–3961.
+const handleObsidianDestroyerDrainMana: RegistryHandler = (state, _raw, _slot) => {
+  state.intents.push({
+    kind: 'cast_triggered_spell',
+    spellId: DRAIN_MANA_ERADICATOR_TRIGGER_SPELL_ID,
+  });
+  state.effects.push({ kind: 'trigger_spell', spellId: DRAIN_MANA_ERADICATOR_TRIGGER_SPELL_ID });
+  return true;
+};
+
+// Mistletoe cheer — HandleEmote(EMOTE_ONESHOT_CHEER) only. Cite: SpellEffects.cpp:3963–3969.
+const handleMistletoeCheer: RegistryHandler = (state, _raw, _slot) => {
+  state.effects.push({
+    kind: 'script_handled_noop',
+    spellId: MISTLETOE_CHEER_SPELL_ID,
+  } as never);
+  return true;
+};
+
+// Mistletoe gift — urand 26206/26207 on player. Cite: SpellEffects.cpp:3971–3979.
+const handleMistletoeRandom: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const spellId =
+    roll01(state) < 0.5 ? MISTLETOE_RANDOM_OUTCOMES[0]! : MISTLETOE_RANDOM_OUTCOMES[1]!;
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+  return true;
+};
+
+// Despawn — ForcedDespawn on creature unitTarget. Cite: SpellEffects.cpp:3981–3987.
+const handleDespawn: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === true) return true;
+  state.effects.push({
+    kind: 'script_handled_noop',
+    spellId: DESPAWN_SCRIPT_SPELL_ID,
+  } as never);
+  return true;
+};
+
+const script: Record<number, RegistryHandler> = {
+  [HALLOWS_END_TRICK_SPELL_ID]: handleHallowsEndTrick,
+  [PIRATE_COSTUME_SPELL_ID]: handlePirateCostume,
+  [NINJA_COSTUME_SPELL_ID]: handleNinjaCostume,
+  [LEPER_GNOME_COSTUME_SPELL_ID]: handleLeperGnomeCostume,
+  [RANDOM_COSTUME_SPELL_ID]: handleRandomCostume,
+  [CANNON_FIRE_SPELL_ID]: handleCannonFire,
+  [GHOST_COSTUME_SPELL_ID]: handleGhostCostume,
+  [MAGIC_WINGS_SPELL_ID]: handleMagicWings,
+  [TRICK_OR_TREAT_SPELL_ID]: handleTrickOrTreat,
+  [SUMMON_RC_TANK_SPELL_ID]: handleSummonRcTank,
+  [DRAIN_MANA_NULLIFIER_TRIGGER_SPELL_ID]: handleDrainManaFeedback,
+  [DRAIN_MANA_ERADICATOR_TRIGGER_SPELL_ID]: handleDrainManaFeedback,
+  [OBSIDIAN_DESTROYER_DRAIN_MANA_SPELL_ID]: handleObsidianDestroyerDrainMana,
+  [MISTLETOE_CHEER_SPELL_ID]: handleMistletoeCheer,
+  [MISTLETOE_RANDOM_SPELL_ID]: handleMistletoeRandom,
+  [DESPAWN_SCRIPT_SPELL_ID]: handleDespawn,
+};
+
+export const si4ScriptGenericBPack: RegistryPack = {
+  id: 'si4-script-generic-b',
+  script,
+};

package/src/engine/spells/interpreter/registry/packs/si4-script-generic-c.ts

@@ -0,0 +1,233 @@
+// EffectScriptEffect SPELLFAMILY_GENERIC ids 26524–30918. Cite: SpellEffects.cpp:3992–4147.
+
+import type { RegistryHandler, RegistryPack, RegistryState } from '../types.ts';
+import {
+  CREATE_HEART_CANDY_SPELL_ID,
+  HEART_CANDY_OUTCOME_SPELL_IDS,
+  HEARTBROKEN_AURA_SPELL_ID,
+  SUMMON_REINDEER_SPELL_ID,
+} from '../../../cmangos-special-cases-s19.ts';
+import { IMPROVED_SPRINT_TRIGGER_SPELL_ID } from '../../../cmangos-special-cases-s21.ts';
+import { IMMUNE_TO_ROOT_AND_SNARE_MASK } from '../../../immunity.ts';
+
+/** Sand Trap parent (Kurinnaxx). Cite: SpellEffects.cpp:3992–3996. */
+export const SAND_TRAP_SCRIPT_SPELL_ID = 26524;
+/** Sand Trap payload cast on unitTarget. Cite: SpellEffects.cpp:3995 CastSpell(…, 25648). */
+export const SAND_TRAP_TRIGGER_SPELL_ID = 25648;
+
+/** Summon Reindeer SCRIPT parent. Cite: SpellEffects.cpp:3998–4002. */
+export const SUMMON_REINDEER_SCRIPT_SPELL_ID = 26528;
+
+/** Valentine guard scripts. Cite: SpellEffects.cpp:4004–4009. */
+export const VALENTINE_GUARD_SPELL_IDS: readonly number[] = [
+  26663, 26923, 26924, 27541, 27547, 27548,
+];
+
+/** Valentine civilian scripts. Cite: SpellEffects.cpp:4063–4064. */
+export const VALENTINE_CIVILIAN_SPELL_IDS: readonly number[] = [27549, 27550];
+
+/** Adored aura gated before Pledge/Gift of Adoration. Cite: SpellEffects.cpp:4030–4033. */
+export const ADORED_AURA_SPELL_ID = 26680;
+/** Love is in the Air aura removed from the NPC caster. Cite: SpellEffects.cpp:4039. */
+export const LOVE_IS_IN_THE_AIR_AURA_SPELL_ID = 27741;
+
+/** Love is in the Air Test. Cite: SpellEffects.cpp:4100–4108. */
+export const LOVE_IS_IN_THE_AIR_TEST_SPELL_ID = 27654;
+/** Amorous cast when target is not an innkeeper. Cite: SpellEffects.cpp:4106. */
+export const AMOROUS_SPELL_ID = 26869;
+/** UNIT_NPC_FLAG_INNKEEPER. Cite: Unit.h:517. */
+export const UNIT_NPC_FLAG_INNKEEPER = 0x00000080;
+
+/** Breath of Sargeras. Cite: SpellEffects.cpp:4132–4138. */
+export const BREATH_OF_SARGERAS_SPELL_ID = 28352;
+/** Breath of Sargeras payload. Cite: SpellEffects.cpp:4137 CastSpell(…, 28342). */
+export const BREATH_OF_SARGERAS_TRIGGER_SPELL_ID = 28342;
+
+// Guard map [Pledge of Friendship, Pledge of Adoration] by caster faction. Cite: SpellEffects.cpp:4016–4024.
+const VALENTINE_GUARD_BY_FACTION: Readonly<Record<number, readonly [number, number]>> = {
+  11: [27242, 27510],
+  85: [27247, 27507],
+  57: [27244, 27506],
+  68: [27246, 27515],
+  71: [27246, 27515],
+  79: [27245, 27504],
+  105: [27248, 27513],
+};
+
+// Civilian map [Gift of Friendship, Gift of Adoration] by caster faction. Cite: SpellEffects.cpp:4071–4079.
+const VALENTINE_CIVILIAN_BY_FACTION: Readonly<Record<number, readonly [number, number]>> = {
+  12: [27525, 27509],
+  29: [27523, 27505],
+  55: [27520, 27503],
+  68: [27529, 27512],
+  80: [27519, 26901],
+  104: [27524, 27511],
+  126: [27523, 27505],
+  875: [27520, 27503],
+};
+
+function roll01(state: RegistryState): number {
+  const r = state.ctx.rng;
+  if (typeof r === 'function') return r();
+  return 0;
+}
+
+function casterFactionOf(state: RegistryState): number | undefined {
+  if (!('casterFaction' in state.ctx)) return undefined;
+  const v = (state.ctx as { casterFaction?: unknown }).casterFaction;
+  return typeof v === 'number' ? v : undefined;
+}
+
+function unitTargetNpcFlagsOf(state: RegistryState): number | undefined {
+  if (!('unitTargetNpcFlags' in state.ctx)) return undefined;
+  const v = (state.ctx as { unitTargetNpcFlags?: unknown }).unitTargetNpcFlags;
+  return typeof v === 'number' ? v : undefined;
+}
+
+function pushUnitTargetCast(state: RegistryState, spellId: number): void {
+  state.intents.push({ kind: 'trigger_spell_as_unit_target', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+}
+
+function pushCasterCast(state: RegistryState, spellId: number): void {
+  state.intents.push({ kind: 'cast_triggered_spell', spellId });
+  state.effects.push({ kind: 'trigger_spell', spellId });
+}
+
+function pushConsumeAura(state: RegistryState, spellId: number): void {
+  state.intents.push({
+    kind: 'consume_aura',
+    spellId,
+    spellFamilyName: 0,
+    spellFamilyFlags: 0,
+    auraType: 0,
+  });
+  state.effects.push({
+    kind: 'consume_aura',
+    spellId,
+    spellFamilyName: 0,
+    spellFamilyFlags: 0,
+    auraType: 0,
+  });
+}
+
+function targetHasAura(state: RegistryState, spellId: number): boolean {
+  const auras = state.ctx.targetAuras ?? [];
+  return auras.some((a) => (a.spellId | 0) === (spellId | 0));
+}
+
+// Sand Trap — unitTarget casts 25648. Cite: SpellEffects.cpp:3992–3996.
+const handleSandTrap: RegistryHandler = (state, _raw, _slot) => {
+  pushUnitTargetCast(state, SAND_TRAP_TRIGGER_SPELL_ID);
+  return true;
+};
+
+// Summon Reindeer — unitTarget casts 26529. Cite: SpellEffects.cpp:3998–4002.
+const handleSummonReindeer: RegistryHandler = (state, _raw, _slot) => {
+  pushUnitTargetCast(state, SUMMON_REINDEER_SPELL_ID);
+  return true;
+};
+
+// Valentine guard/civilian — faction table, 1/6 Heartbroken, else Adored/Friendship. Cite: :4004–4098.
+function handleValentine(
+  state: RegistryState,
+  byFaction: Readonly<Record<number, readonly [number, number]>>,
+): boolean {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  const faction = casterFactionOf(state);
+  if (faction == null) {
+    state.effects.push({ kind: 'script_handled_noop', spellId: state.spell.id | 0 } as never);
+    return true;
+  }
+  const pair = byFaction[faction | 0];
+  if (!pair) {
+    state.effects.push({ kind: 'script_handled_noop', spellId: state.spell.id | 0 } as never);
+    return true;
+  }
+  // !urand(0, 5) → 1 in 6 Heartbroken. Cite: SpellEffects.cpp:4028–4029 / :4084–4085.
+  const roll = state.ctx.rng ? Math.floor(roll01(state) * 6) : 0;
+  let pledgeOrBroken: number;
+  if (roll === 0) {
+    pledgeOrBroken = HEARTBROKEN_AURA_SPELL_ID;
+  } else if (!targetHasAura(state, ADORED_AURA_SPELL_ID)) {
+    pledgeOrBroken = pair[1]!;
+    pushUnitTargetCast(state, ADORED_AURA_SPELL_ID);
+  } else {
+    pledgeOrBroken = pair[0]!;
+  }
+  pushUnitTargetCast(state, pledgeOrBroken);
+  // Remove Love is in the Air from the NPC caster. Cite: SpellEffects.cpp:4039 / :4095.
+  pushConsumeAura(state, LOVE_IS_IN_THE_AIR_AURA_SPELL_ID);
+  return true;
+}
+
+const handleValentineGuard: RegistryHandler = (state, _raw, _slot) =>
+  handleValentine(state, VALENTINE_GUARD_BY_FACTION);
+
+const handleValentineCivilian: RegistryHandler = (state, _raw, _slot) =>
+  handleValentine(state, VALENTINE_CIVILIAN_BY_FACTION);
+
+// Create Heart Candy — urand(0,7) → create-item scripts. Cite: SpellEffects.cpp:4044–4060.
+const handleCreateHeartCandy: RegistryHandler = (state, _raw, _slot) => {
+  const idx = state.ctx.rng ? Math.floor(roll01(state) * 8) % 8 : 0;
+  const spellId = HEART_CANDY_OUTCOME_SPELL_IDS[idx]!;
+  pushCasterCast(state, spellId);
+  return true;
+};
+
+// Love is in the Air Test — gossip flag + Amorous when not innkeeper. Cite: SpellEffects.cpp:4100–4108.
+const handleLoveIsInTheAirTest: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer !== false) {
+    state.effects.push({
+      kind: 'script_handled_noop',
+      spellId: LOVE_IS_IN_THE_AIR_TEST_SPELL_ID,
+    } as never);
+    return true;
+  }
+  const flags = unitTargetNpcFlagsOf(state);
+  const isInnkeeper = flags != null && (flags & UNIT_NPC_FLAG_INNKEEPER) !== 0;
+  if (!isInnkeeper) {
+    // unitTarget casts Amorous on m_caster. Cite: SpellEffects.cpp:4106.
+    pushUnitTargetCast(state, AMOROUS_SPELL_ID);
+  } else {
+    // SetFlag(GOSSIP) only — no spell-intent kind. Cite: SpellEffects.cpp:4104.
+    state.effects.push({
+      kind: 'script_handled_noop',
+      spellId: LOVE_IS_IN_THE_AIR_TEST_SPELL_ID,
+    } as never);
+  }
+  return true;
+};
+
+// Breath of Sargeras — player unitTarget casts 28342. Cite: SpellEffects.cpp:4132–4138.
+const handleBreathOfSargeras: RegistryHandler = (state, _raw, _slot) => {
+  if (state.ctx.unitTargetIsPlayer === false) return true;
+  pushUnitTargetCast(state, BREATH_OF_SARGERAS_TRIGGER_SPELL_ID);
+  return true;
+};
+
+// Improved Sprint — purge root+snare. Cite: SpellEffects.cpp:4140–4147; SharedDefines.h:389–390.
+const handleImprovedSprint: RegistryHandler = (state, _raw, _slot) => {
+  state.intents.push({
+    kind: 'mechanic_immunity_purge',
+    mechanic: 0,
+    mechanicMask: IMMUNE_TO_ROOT_AND_SNARE_MASK,
+  });
+  return true;
+};
+
+const script: Record<number, RegistryHandler> = {
+  [SAND_TRAP_SCRIPT_SPELL_ID]: handleSandTrap,
+  [SUMMON_REINDEER_SCRIPT_SPELL_ID]: handleSummonReindeer,
+  [CREATE_HEART_CANDY_SPELL_ID]: handleCreateHeartCandy,
+  [LOVE_IS_IN_THE_AIR_TEST_SPELL_ID]: handleLoveIsInTheAirTest,
+  [BREATH_OF_SARGERAS_SPELL_ID]: handleBreathOfSargeras,
+  [IMPROVED_SPRINT_TRIGGER_SPELL_ID]: handleImprovedSprint,
+};
+for (const id of VALENTINE_GUARD_SPELL_IDS) script[id] = handleValentineGuard;
+for (const id of VALENTINE_CIVILIAN_SPELL_IDS) script[id] = handleValentineCivilian;
+
+export const si4ScriptGenericCPack: RegistryPack = {
+  id: 'si4-script-generic-c',
+  script,
+};

package/src/engine/spells/interpreter/registry/types.ts

@@ -0,0 +1,48 @@
+// SI4 scripted-spell registry types. Handlers keyed by spell id (and optional family keys), not by
+// unfinished generics. Design: docs/archive/SPELL-INTERPRETER.md §2.3.
+
+import type { RawSpellEffect, SpellDef, SpellEffect } from '../../../../data/schema.ts';
+import type { InterpretContext, InterpretIntent, UnhandledSlot } from '../types.ts';
+
+// Mutable interpreter state shared with EFFECT_HANDLERS. Structural subset of handlers.ts HandlerState
+// (avoids circular import).
+export interface RegistryState {
+  spell: SpellDef;
+  ctx: InterpretContext;
+  effects: SpellEffect[];
+  unhandled: UnhandledSlot[];
+  intents: InterpretIntent[];
+}
+
+// A per-spell dummy or script handler, returning true when the slot is fully handled — an intentional
+// no-op included. Cite: SpellEffects.cpp EffectDummy / EffectScriptEffect per-id cases.
+export type RegistryHandler = (
+  state: RegistryState,
+  raw: RawSpellEffect,
+  slot: number,
+) => boolean;
+
+// A rank-generic matcher, selecting a handler by family, flags or icon instead of a per-rank id table.
+// Prefer it, so later ranks cannot die silently when only rank 1 was registered.
+export interface RegistryMatcher {
+  spellFamilyName?: number;
+  spellFamilyFlags?: number;
+  spellIconId?: number;
+  handler: RegistryHandler;
+}
+
+// A pack of handlers for one family or batch. Prefer the rank-generic matchers, and keep id maps only
+// where the C++ itself scripts specific ids, with the citation next to the id.
+export interface RegistryPack {
+  /** Pack id for diagnostics (not used in dispatch). */
+  id: string;
+  // The dummy effect by exact spell id, only where the C++ uses per-id cases.
+  // Deprecated in favour of the rank-generic matchers.
+  dummy?: Readonly<Record<number, RegistryHandler>>;
+  /** SPELL_EFFECT_SCRIPT_EFFECT (77) by exact spell id — only when CMaNGOS uses per-id. */
+  script?: Readonly<Record<number, RegistryHandler>>;
+  /** Rank-generic DUMMY dispatch (family / flags / icon). Checked after exact id. */
+  dummyMatchers?: readonly RegistryMatcher[];
+  /** Rank-generic SCRIPT_EFFECT dispatch. Checked after exact id. */
+  scriptMatchers?: readonly RegistryMatcher[];
+}