feat: module 04 interceptors

Trigger multipliers as aura data on cards, snapshotted by an Aura Update
(Other) after each Death Creation Step and on summon, and applied by one
generic routine (activations) when each queued trigger starts. Baron
Rivendare is content only (stacking "max"); Brann Bronzebeard is the
content-only Expansion Drop. Adds play (now required) and Battlecry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

course/04-interceptors/reference/ts/src/engine/queue.ts

@@ -0,0 +1,201 @@
+// The action queue: how one player action (a Sequence) resolves.
+//
+// Performing an action changes the world and produces events. Every trigger that
+// responds to those events goes into one Queue, oldest listener first, and the Queue
+// is locked. Each queued trigger then resolves completely, including everything
+// its own actions cause, before the next one starts: depth-first.
+//
+// Module 3: nothing leaves play mid-Sequence. When the outermost Phase ends, the
+// Death Creation Step removes the dead, and a Death Phase resolves their
+// Deathrattles. That repeats until a step finds no new deaths.
+//
+// Module 4: a queued trigger may activate more than once. How many times is
+// decided by one routine, `activations` in `aura.ts`, from aura data on cards.
+// Nothing here knows which cards multiply which triggers.
+
+import { activations, auraUpdateOther } from "./aura";
+import type { Trigger, TriggerOn } from "./card";
+import { deathCreationStep } from "./death";
+import type { Event } from "./event";
+import type { EntityId, PlayerId, World } from "./world";
+
+/** Something the engine can do. Card effects return these instead of changing the world. */
+export type Action =
+  /** Deal `amount` to each target at once: all damage first, then the reactions. */
+  | { type: "damage"; targets: EntityId[]; amount: number }
+  | { type: "draw"; player: PlayerId }
+  | { type: "gainArmor"; player: PlayerId; amount: number }
+  | { type: "gainAttack"; id: EntityId; amount: number }
+  | { type: "cast"; card: string; player: PlayerId; target?: EntityId }
+  /** Mark each target pending destroy. They leave play in the next Death Creation Step. */
+  | { type: "destroy"; targets: EntityId[] }
+  /** Summon `card` for `player` at board index `at`, or at the right end if `at` is undefined. */
+  | { type: "summon"; card: string; player: PlayerId; at?: number }
+  /** Play a minion from its owner's hand: it enters the right end of the board, then its Battlecry resolves. */
+  | { type: "play"; id: EntityId };
+
+/** What an effect may look at when it runs. */
+export class Ctx {
+  constructor(
+    readonly world: World,
+    /** The player the effect works for. */
+    readonly owner: PlayerId,
+    /** The minion whose trigger is resolving; undefined for a spell. */
+    readonly source?: EntityId,
+    /** The chosen target, if any. */
+    readonly target?: EntityId,
+    /**
+     * The source's board position. For a Deathrattle, the source has left play,
+     * and this is the position its Death Event remembered.
+     */
+    readonly position?: number,
+  ) {}
+
+  /** The minion whose trigger is resolving. */
+  minion(): EntityId {
+    if (this.source === undefined) throw new Error("only a triggered ability has a source");
+    return this.source;
+  }
+
+  enemyHero(): EntityId {
+    return this.world.hero(this.owner === 0 ? 1 : 0);
+  }
+}
+
+/** Run one Sequence: a player action and everything it causes. */
+export function runSequence(world: World, action: Action): void {
+  perform(world, action);
+  // The outermost Phase has ended. Each Death Phase is itself an outermost
+  // Phase, so the end-of-Phase steps run again after it, until nothing dies.
+  let deaths = endOfOutermostPhase(world);
+  for (let round = 1; deaths.length > 0; round++) {
+    world.record({ type: "DeathPhase", round });
+    react(world, deaths);
+    deaths = endOfOutermostPhase(world);
+  }
+}
+
+/**
+ * The steps that run only when the outermost Phase ends; returns the Death Events.
+ * Hearthstone runs an Aura Update (Health/Attack) first. The course has no
+ * Health/Attack auras, so that step has nothing to do and is left out.
+ */
+function endOfOutermostPhase(world: World): Event[] {
+  const deaths = deathCreationStep(world);
+  // After the step: a minion that just died no longer contributes its auras
+  // to the Death Phase that resolves these deaths.
+  auraUpdateOther(world);
+  return deaths;
+}
+
+/** Summon `card` for `player` at board index `at` (or the right end). Summoning runs an Aura Update. */
+export function summon(world: World, card: string, player: PlayerId, at?: number): EntityId {
+  const id = world.create(card, player, "board", at);
+  auraUpdateOther(world);
+  return id;
+}
+
+function perform(world: World, action: Action): void {
+  switch (action.type) {
+    case "damage": {
+      // Area damage: every Damage Event is created, in order of play, before any reaction.
+      const targets = [...action.targets].sort((a, b) => world.orderOfPlay(a)! - world.orderOfPlay(b)!);
+      const events: Event[] = [];
+      for (const target of targets) {
+        world.damage(target, action.amount);
+        events.push({ type: "Damaged", target, amount: action.amount });
+      }
+      react(world, events);
+      break;
+    }
+    case "draw":
+      world.draw(action.player);
+      break;
+    case "gainArmor":
+      world.gainArmor(action.player, action.amount);
+      break;
+    case "gainAttack":
+      world.gainAttack(action.id, action.amount);
+      break;
+    case "destroy":
+      for (const target of action.targets) world.markDestroyed(target);
+      break;
+    case "summon":
+      summon(world, action.card, action.player, action.at);
+      break;
+    case "play": {
+      if (world.zoneOf(action.id) !== "hand") throw new Error(`play: entity ${action.id} is not in a hand`);
+      // Playing is not summoning: no Aura Update here. The played minion's own
+      // auras join at the end of the outermost Phase.
+      world.moveTo(action.id, "board");
+      const played: Event = { type: "Played", id: action.id };
+      world.record(played);
+      react(world, [played]);
+      break;
+    }
+    case "cast": {
+      const effect = world.card(action.card).onCast;
+      if (!effect) throw new Error(`"${action.card}" is not a spell`);
+      world.record({ type: "SpellCast", card: action.card });
+      for (const next of effect(new Ctx(world, action.player, undefined, action.target))) perform(world, next);
+      break;
+    }
+  }
+}
+
+/** A Phase: queue every trigger that responds to `events`, then resolve them one by one. */
+function react(world: World, events: Event[]): void {
+  // Fill the Queue: for each event (already in order of play), each listener in order of play.
+  const queue: [EntityId, Trigger, Event][] = [];
+  for (const event of events) {
+    for (const listener of listeners(world, event)) {
+      for (const trigger of world.card(world.cardName(listener)).triggers) {
+        if (responds(world, trigger.on, listener, event)) queue.push([listener, trigger, event]);
+      }
+    }
+  }
+  // The Queue is now locked: nothing that happens below adds to it.
+  for (const [source, trigger, event] of queue) {
+    // The interceptor: the entry was queued once; the auras in force when it
+    // starts decide how many times it activates, back to back.
+    const times = activations(world, world.ownerOf(source), trigger.on);
+    for (let i = 0; i < times; i++) {
+      world.record({ type: "Triggered", source, on: trigger.on });
+      const position = event.type === "Destroyed" && event.id === source ? event.position : world.boardIndex(source);
+      const actions = trigger.effect(new Ctx(world, world.ownerOf(source), source, undefined, position));
+      // Depth-first: each action, and every reaction it causes, finishes before the next.
+      for (const action of actions) perform(world, action);
+    }
+  }
+}
+
+/**
+ * Who may respond to `event`, in order of play: every minion in play and, for a
+ * Death Event, the minion that died. It has left play, but its Deathrattle still answers.
+ */
+function listeners(world: World, event: Event): EntityId[] {
+  const inPlay = world.minionsInPlay();
+  if (event.type !== "Destroyed") return inPlay;
+  return [...inPlay, event.id].sort((a, b) => world.orderOfPlay(a)! - world.orderOfPlay(b)!);
+}
+
+/** Does a trigger listening for `on`, belonging to `listener`, respond to `event`? */
+function responds(world: World, on: TriggerOn, listener: EntityId, event: Event): boolean {
+  if (event.type === "Destroyed") return on === "deathrattle" && event.id === listener;
+  if (event.type === "Played") return on === "battlecry" && event.id === listener;
+  if (event.type !== "Damaged") return false;
+  const isMinion = !world.isHero(event.target);
+  switch (on) {
+    case "selfDamaged":
+      return event.target === listener;
+    case "friendlyMinionDamaged":
+      return isMinion && world.ownerOf(event.target) === world.ownerOf(listener);
+    case "anyMinionDamaged":
+      return isMinion;
+    case "heroDamaged":
+      return !isMinion;
+    case "deathrattle":
+    case "battlecry":
+      return false;
+  }
+}