azeroth-shell 0.0.0-stage → 0.1.1

package/src/engine/combat/hostileItemUse.ts

@@ -0,0 +1,75 @@
+// Throwing an offensive item — grenades, bombs, Tidal Charm, Magic Dust. A thrown item is REPLAYED AS
+// A CAST, so the fan-out, the hit table, immunities and threat are the real ones.
+
+import type { CombatEvent, Side } from '../core/events.ts';
+import type { CombatantId } from './threat.ts';
+import type { CombatItem, Fighter } from './types.ts';
+import type { SpellDef } from '../../data/schema.ts';
+import { spendKitItem } from './types.ts';
+
+/** Everything the throw needs from the enclosing session. */
+export interface HostileItemUseDeps {
+  /** Current session clock (ms). */
+  t: number;
+  /** The unit throwing it. */
+  caster: Fighter;
+  /** Side label for the log row. */
+  actor: Side;
+  /** Explicit target from the action, or undefined for "pick one for me". */
+  targetId: CombatantId | undefined;
+  /** Resolve an explicit CombatantId to a Fighter (null when that side is absent). */
+  resolveItemTarget: (id: CombatantId) => Fighter | null;
+  /** Living hostile units for `caster`, nearest/first-priority first. */
+  livingHostilesFor: (f: Fighter) => Fighter[];
+  /** Is this side hostile to the ACTOR? (An enemy bot's grenade lands on player-faction sides.) */
+  hostileToActor: (s: Side) => boolean;
+  dead: (f: Fighter) => boolean;
+  /** The shared cast seam (applySpell + AoE fan-out + ScriptDev hooks). */
+  castOnTargets: (src: Fighter, primary: Fighter, spell: SpellDef) => void;
+  push: (e: CombatEvent) => void;
+  cdMap: Map<number, number>;
+  spentMap: Map<number, number>;
+}
+
+// Throw `it` at a hostile unit, returning whether it fired. An offensive item may ONLY land on a
+// living enemy: with no explicit target, 43 of 43 of them used to detonate on the user.
+export function useHostileItem(
+  it: CombatItem,
+  effect: Extract<CombatItem['effect'], { kind: 'hostile_cast' }>,
+  d: HostileItemUseDeps,
+): boolean {
+  const foe = d.targetId == null
+    ? (d.livingHostilesFor(d.caster)[0] ?? null)
+    : d.resolveItemTarget(d.targetId);
+  if (!foe || !d.hostileToActor(foe.side) || d.dead(foe)) {
+    return false;
+  }
+
+  // Shared category CD (bombs = spellcategory 24 / 60000 ms) — refuse while category is hot.
+  // Cite: item_template.spellcategory_1; docs/profid/C2-engineering.md Q3.
+  if (
+    it.category != null
+    && it.categoryCooldownMs != null
+    && it.categoryCooldownMs > 0
+    && (d.caster.categoryCooldowns.get(it.category) ?? 0) > d.t
+  ) {
+    return false;
+  }
+
+  // Replayed as a real cast so the fan uses the spell's own radius and shape. Damage and CC rows for
+  // every unit in radius come from that path — do not reimplement the fan here.
+  d.castOnTargets(d.caster, foe, effect.spell);
+
+  spendKitItem(it, d.spentMap);
+  if (it.cooldownMs > 0) d.cdMap.set(it.entry, d.t + it.cooldownMs);
+  if (it.category != null && it.categoryCooldownMs != null && it.categoryCooldownMs > 0) {
+    d.caster.categoryCooldowns.set(it.category, d.t + it.categoryCooldownMs);
+  }
+  // The damage and cc rows come from the cast path above; this is the "you threw it" beat.
+  // Primary only on item_use — secondaries appear as their own spell_hit / control rows.
+  d.push({
+    t: d.t, kind: 'item_use', actor: d.actor, entry: it.entry, name: it.name,
+    effect: 'hostile_cast', amount: 0, target: foe.side,
+  });
+  return true;
+}

package/src/engine/combat/interruptAuras.ts

@@ -0,0 +1,66 @@
+// RemoveAurasWithInterruptFlags — drop every holder whose spell carries one of the bits. Three had a
+// consumer already; hostile action, moving and item use did not. Standing and looting have no state.
+
+import type { CombatContext } from './context.ts';
+import type { Fighter } from './types.ts';
+import { AURA_INTERRUPT } from '../../domain/spells/stealth.ts';
+import { dropFeignDeath } from './combatFlag.ts';
+import { DISPEL_TYPE } from '../../domain/spells/dispel.ts';
+
+export { AURA_INTERRUPT };
+
+export interface InterruptAurasDeps {
+  /** powerForm's stealth break, which already reads the unit's own `stealthBreakFlags`. */
+  maybeBreakStealthOn: (f: Fighter, flag: number, reason: string) => void;
+}
+
+export function installInterruptAuras(ctx: CombatContext, deps: InterruptAurasDeps): void {
+  const aifOf = (spellId: number): number => {
+    const lookup = ctx.auraInterruptFlagsOf;
+    return lookup ? (lookup(spellId | 0) | 0) : 0;
+  };
+
+  // Every live holder whose spell carries any bit in the mask is removed. Stealth routes through the
+  // existing break so the form, chip and log line stay in one place; Feign Death has its own pose.
+  const removeAurasWithInterruptFlags = (
+    f: Fighter,
+    flags: number,
+    reason: string,
+    // Cast start owns both: it runs the ALLOW_WHILE_STEALTHED-guarded break itself, and
+    // RemoveAurasOnCast never drops the caster's own holder. Cite: Unit.cpp:5247-5251.
+    opts?: { skipStealth?: boolean; exceptSpellId?: number; skipInvisibility?: boolean },
+  ): void => {
+    const mask = flags | 0;
+    if (!mask) return;
+    if (f.stealthed && !opts?.skipStealth) deps.maybeBreakStealthOn(f, mask, reason);
+    const feignId = f.feignSpellId | 0;
+    if (f.feigningUntil > ctx.t && feignId && (aifOf(feignId) & mask) !== 0) {
+      const sid = dropFeignDeath(f);
+      if (sid) {
+        for (const e of ctx.effectsOn(f.side)) {
+          if (e.spellId === sid) {
+            e.expiresAt = Math.min(e.expiresAt, ctx.t);
+            ctx.touchEffect(e);
+          }
+        }
+        ctx.push({ t: ctx.t, kind: 'aura', actor: f.side, name: 'Feign Death', applied: false });
+      }
+    }
+    // Anything else the unit is holding. setPos calls this for every moving unit every tick, so
+    // it reads the by-target index (createSession effectsOn) rather than the whole effect list.
+    const held = ctx.effectsOn(f.side);
+    for (let i = held.length - 1; i >= 0; i--) {
+      const e = held[i];
+      if (!e || !e.spellId) continue;
+      if (e.expiresAt <= ctx.t) continue;
+      if (opts?.exceptSpellId && e.spellId === opts.exceptSpellId) continue;
+      if ((aifOf(e.spellId) & mask) === 0) continue;
+      if (opts?.skipInvisibility && ctx.dispelTypeOfSpell?.(e.spellId) === DISPEL_TYPE.INVISIBILITY) continue;
+      e.expiresAt = ctx.t;
+      ctx.touchEffect(e);
+      f.buffActive.delete(e.spellId);
+    }
+  };
+
+  ctx.removeAurasWithInterruptFlags = removeAurasWithInterruptFlags;
+}

package/src/engine/combat/itemRescue.ts

@@ -0,0 +1,49 @@
+// BG auto-rescue kit-item path, peeled out of stepSession.ts at its filesize ceiling.
+// Behaviour is byte-identical to the three closures it replaces (W12).
+
+import type { CombatContext } from './context.ts';
+import type { CombatItem, Fighter } from './types.ts';
+
+export interface ItemRescue {
+  /** This unit's item bag + per-entry cooldown map, or null when it carries none. */
+  bagAndCdOf(f: Fighter): { bag: readonly CombatItem[]; cd: Map<number, number> } | null;
+  /** Does `entry` in this unit's bag carry the immunity that cancels the control on it? */
+  itemBreaksControl(f: Fighter, entry: number): boolean;
+  /** Pop the first usable kit item whose own immunity cancels the control on `f`. */
+  tryItemRescue(f: Fighter): boolean;
+}
+
+export function createItemRescue(
+  ctx: CombatContext,
+  useItem: (entry: number, from: string, to: string) => boolean,
+): ItemRescue {
+  const bagAndCdOf = (f: Fighter): { bag: readonly CombatItem[]; cd: Map<number, number> } | null => {
+    if (f === ctx.player) return { bag: ctx.playerItems, cd: ctx.itemCd };
+    const bag = ctx.unitItems.get(f.side);
+    const cd = ctx.unitItemCd.get(f.side);
+    return bag && cd ? { bag, cd } : null;
+  };
+
+  const itemBreaksControl = (f: Fighter, entry: number): boolean => {
+    const it = bagAndCdOf(f)?.bag.find((x) => x.entry === entry);
+    if (!it || it.count <= 0 || it.effect.kind !== 'friendly_cast') return false;
+    return ctx.spellCancelsOwnControl?.(f, it.effect.spell) === true;
+  };
+
+  /** cfg.autoRescueItems: the trinket/FAP a player would tap, fired for AI units too. */
+  const tryItemRescue = (f: Fighter): boolean => {
+    const kit = bagAndCdOf(f);
+    if (!kit || f.castingSpell) return false;
+    for (const it of kit.bag) {
+      if (it.count <= 0 || it.effect.kind !== 'friendly_cast') continue;
+      if ((kit.cd.get(it.entry) ?? 0) > ctx.t) continue;
+      if (it.category != null && it.categoryCooldownMs != null && it.categoryCooldownMs > 0
+        && (f.categoryCooldowns.get(it.category) ?? 0) > ctx.t) continue;
+      if (ctx.spellCancelsOwnControl?.(f, it.effect.spell) !== true) continue;
+      if (useItem(it.entry, f.side, f.side)) return true;
+    }
+    return false;
+  };
+
+  return { bagAndCdOf, itemBreaksControl, tryItemRescue };
+}

package/src/engine/combat/itemUse.ts

@@ -0,0 +1,260 @@
+// Peeled from createSession (createSession.md P8) — pattern (D).
+// resolveItemTarget / useItem (hostile_cast stays in hostileItemUse leaf).
+
+import type { CombatContext } from './context.ts';
+import type { CombatItem, Fighter } from './types.ts';
+import type { Side } from '../core/events.ts';
+import { isAllySide, isEnemySide } from '../core/events.ts';
+import type { CombatantId } from './threat.ts';
+import { rollBetween } from './formulas.ts';
+import { applyBuffMod } from './fighterFactory.ts';
+import { maxPowerOfType, powerOfType, setPowerOfType } from './powerPools.ts';
+import { POWER_MANA } from '../spells/effects.ts';
+import { useHostileItem } from './hostileItemUse.ts';
+import { AURA_INTERRUPT } from '../../domain/spells/stealth.ts';
+import { hasAttrEx4, SPELL_ATTR_EX4 } from '../spells/spellAttributes.ts';
+import { spendKitItem } from './types.ts';
+import { emitSimEffect } from './simEffects.ts';
+import { refuseCmangosCheckCast } from './cmangosCastGates.ts';
+import { isPlayerCharacterTarget } from './castTargetGates.ts';
+
+export function installItemUse(ctx: CombatContext): void {
+  const dead = (f: Fighter): boolean =>
+    ((ctx as { dead?: (f: Fighter) => boolean }).dead?.(f) ?? !(f.hp > 0));
+
+  /** Item-use target; null when side absent. */
+  const resolveItemTarget = (targetId: CombatantId): Fighter | null => {
+    if (targetId === 'player') return ctx.player;
+    if (targetId === 'pet') return ctx.pet;
+    if (isAllySide(targetId) || isEnemySide(targetId)) return ctx.sideFighter?.(targetId) ?? null;
+    return null;
+  };
+
+  /** Friendly unit sides legal for restore_health / restore_power / apply_buff item effects. */
+  const isItemFriendlySide = (s: Side): boolean =>
+    s === 'player' || s === 'pet' || isAllySide(s);
+
+  // Use a carried consumable: an instant restore or buff on the target, defaulting to self, then
+  // decrement and start the cooldown. Off the GCD but blocked while casting, and friendly-only.
+  const useItem = (entry: number, targetId?: CombatantId, actor: Side = 'player'): boolean => {
+    let bag: CombatItem[];
+    let cdMap: Map<number, number>;
+    let spentMap: Map<number, number>;
+    let caster: Fighter;
+    if (actor === 'player') {
+      bag = ctx.playerItems;
+      cdMap = ctx.itemCd;
+      spentMap = ctx.itemsSpent;
+      caster = ctx.player;
+    } else if (isAllySide(actor) || isEnemySide(actor)) {
+      // One lookup by side. BG enemy bots quaff from their own kits; an enemy injected
+      // mid-fight (EventAI summon) has no bag entry and the empty fallback refuses cleanly.
+      const unit = ctx.bySide(actor as Side);
+      if (!unit || unit.side !== actor) return false;
+      bag = ctx.unitItems.get(actor as Side) ?? [];
+      cdMap = ctx.unitItemCd.get(actor as Side) ?? new Map();
+      spentMap = ctx.unitItemsSpent.get(actor as Side) ?? new Map();
+      caster = unit;
+    } else {
+      return false;
+    }
+    // "Friendly" for an item is relative to who uses it — an enemy bot's potion lands on
+    // enemy sides, its grenade on ours. Totem/summon sides stay untargetable, as before.
+    const actorIsEnemyFaction = isEnemySide(actor);
+    const friendlyToActor = (s: Side): boolean =>
+      actorIsEnemyFaction ? isEnemySide(s) : isItemFriendlySide(s);
+    const hostileToActor = (s: Side): boolean =>
+      actorIsEnemyFaction ? isItemFriendlySide(s) : isEnemySide(s);
+    const selfTarget: CombatantId = actor;
+    const resolvedTargetId = targetId ?? selfTarget;
+
+    const it = bag.find((x) => x.entry === entry);
+    if (!it || it.count <= 0 || (cdMap.get(entry) ?? 0) > ctx.t) return false;
+    // An item's use spell runs CheckCast like any cast: a hardcast OR a live channel refuses it with
+    // SPELL_IN_PROGRESS unless the use spell itself allows casting while casting.
+    // Cite: Spell.cpp:5902; Unit.cpp:4351-4359 IsNonMeleeSpellCasted; SpellDefines.h:181.
+    const useSpell = 'spell' in it.effect ? it.effect.spell : undefined;
+    const busy = !!caster.castingSpell || (!!caster.channeling && caster.channeling.endsAt > ctx.t);
+    if (busy && !hasAttrEx4(useSpell, SPELL_ATTR_EX4.ALLOW_CAST_WHILE_CASTING)) return false;
+    // A charge-bearing unit with none left refuses before any effect, and is not destroyed by trying.
+    // Cite: Spell.cpp:6462-6465 CheckItems SPELL_FAILED_NO_CHARGES_REMAIN.
+    if (it.charges != null && it.charges <= 0) return false;
+    // Shared category CD (potions=4 / bombs=24) from item_template.spellcategory_*.
+    if (
+      it.category != null
+      && it.categoryCooldownMs != null
+      && it.categoryCooldownMs > 0
+      && (caster.categoryCooldowns.get(it.category) ?? 0) > ctx.t
+    ) {
+      return false;
+    }
+
+    const stampItemCds = (): void => {
+      if (it.cooldownMs > 0) cdMap.set(entry, ctx.t + it.cooldownMs);
+      if (it.category != null && it.categoryCooldownMs != null && it.categoryCooldownMs > 0) {
+        caster.categoryCooldowns.set(it.category, ctx.t + it.categoryCooldownMs);
+      }
+    };
+
+    // Offensive on-use (grenade / bomb / Tidal Charm) — handled up front and returned, so
+    // everything below stays the friendly-only path it has always been. See hostileItemUse.ts.
+    if (it.effect.kind === 'hostile_cast') {
+      return useHostileItem(it, it.effect, {
+        t: ctx.t,
+        caster,
+        actor,
+        targetId,
+        resolveItemTarget,
+        livingHostilesFor: ctx.livingHostilesFor,
+        hostileToActor,
+        dead,
+        castOnTargets: ctx.castOnTargets!,
+        push: ctx.push,
+        cdMap,
+        spentMap,
+      });
+    }
+
+    const tgt = resolveItemTarget(resolvedTargetId);
+    if (!tgt) return false;
+    // Heal/buff items: actor's own faction only. Reject foes / totems / missing units before any RNG.
+    if (!friendlyToActor(tgt.side)) return false;
+    if (dead(tgt)) return false;
+
+    // A defensive on-use is replayed as a real cast on the friendly target, the mirror of the hostile
+    // path. That seam is what lets a feared flag carrier trinket out rather than a flattened copy.
+    if (it.effect.kind === 'friendly_cast') {
+      // Rocket Boots blow up instead of firing. The buff never lands, the boots are destroyed
+      // (reusable or not) and the malfunction spell hits the USER, not the item's target.
+      const mf = it.malfunction;
+      // CheckCast before spend: a refused bandage must not eat the item.
+      // Cite: Spell.cpp:3114 MECHANIC_BANDAGE; Spell.cpp CheckCast then TakeCastItem.
+      if (it.effect.spell.mechanic === 'bandage' && refuseCmangosCheckCast(it.effect.spell, {
+        flags: tgt.spec.flags,
+        creatureEntry: tgt.spec.creatureEntry,
+        powerType: tgt.spec.powerType,
+        classId: tgt.spec.classId,
+        auraSpellIds: tgt.buffActive,
+        isPlayer: isPlayerCharacterTarget(tgt),
+      }, {
+        mapId: caster.spec.mapId,
+        hasActivePet: !!ctx.livingPetOf?.(caster) || ctx.isCharmed(caster),
+      }, false)) return false;
+      if (mf && tgt === caster && ctx.rng.next() * 100 < mf.chancePct) {
+        ctx.castOnTargets!(caster, caster, mf.spell);
+        it.count = 0;
+        spentMap.set(entry, (spentMap.get(entry) ?? 0) + 1);
+        // The wreck goes to the PLAYER's bags only; a bot's kit is rebuilt every match.
+        if (actor === 'player') {
+          ctx.itemsGained.set(mf.destroysInto, (ctx.itemsGained.get(mf.destroysInto) ?? 0) + 1);
+        }
+        stampItemCds();
+        ctx.push({
+          t: ctx.t, kind: 'item_use', actor, entry, name: it.name, effect: 'apply_buff', amount: 0,
+        });
+        return true;
+      }
+      ctx.castOnTargets!(caster, tgt, it.effect.spell);
+      spendKitItem(it, spentMap);
+      stampItemCds();
+      ctx.push({
+        t: ctx.t, kind: 'item_use', actor, entry, name: it.name, effect: 'apply_buff', amount: 0,
+        ...(tgt.side === actor ? {} : { target: tgt.side }),
+      });
+      return true;
+    }
+
+    const itemUseEvt = (
+      effect: 'restore_health' | 'restore_power' | 'apply_buff',
+      amount: number,
+    ): void => {
+      // Omit target when self so existing solo log shapes stay compatible.
+      if (tgt.side === actor) {
+        ctx.push({ t: ctx.t, kind: 'item_use', actor, entry, name: it.name, effect, amount });
+      } else {
+        ctx.push({ t: ctx.t, kind: 'item_use', actor, entry, name: it.name, effect, amount, target: tgt.side });
+      }
+    };
+
+    if (it.effect.kind === 'apply_buff') {
+      // A multi-effect buff consumable replays the item's own spell, so every effect lands and
+      // reverses exactly as a cast would. The flat mod path below can only carry one.
+      const whole = it.effect.spell;
+      if (whole) {
+        ctx.castOnTargets!(caster, tgt, whole);
+        spendKitItem(it, spentMap);
+        stampItemCds();
+        itemUseEvt('apply_buff', it.effect.amount);
+        return true;
+      }
+      const { mod, amount, durationMs } = it.effect;
+      // Prefer real spell id from useSpell; pure useBuff keys chips by item entry.
+      const spellId = it.effect.spellId ?? it.entry;
+      const expAt = durationMs > 0 ? ctx.t + durationMs : Number.POSITIVE_INFINITY;
+      const liveBuff = ctx.effectsOn(tgt.side).find(
+        (e) => e.kind === 'buff' && e.spellId === spellId && e.source === actor,
+      );
+      if (!liveBuff) {
+        applyBuffMod(tgt, mod, amount);
+        tgt.buffActive.add(spellId);
+        ctx.effects.push({
+          kind: 'buff', source: actor, target: tgt.side, spellId, name: it.name,
+          mod, amount, expiresAt: expAt,
+        });
+        ctx.push({ t: ctx.t, kind: 'aura', actor: tgt.side, name: it.name, applied: true });
+      } else {
+        // Refresh duration without double-adding flat mods (same as spell buff refresh).
+        liveBuff.expiresAt = expAt;
+        liveBuff.amount = amount;
+        liveBuff.mod = mod;
+        liveBuff.name = it.name;
+        ctx.touchEffect(liveBuff);
+      }
+      spendKitItem(it, spentMap);
+      stampItemCds();
+      itemUseEvt('apply_buff', amount);
+      return true;
+    }
+
+    const amount = Math.max(1, Math.round(rollBetween(it.effect.min, it.effect.max, ctx.rng.next())));
+    if (it.effect.kind === 'restore_health') {
+      tgt.hp = Math.min(tgt.spec.maxHealth, Math.round(tgt.hp + amount));
+    } else {
+      // restore_power — the potion fills the pool its energize names, so a Mana Potion on a warrior
+      // restores nothing rather than 100 rage. Cite: SpellEffects.cpp EffectEnergize EffectMiscValue.
+      const pwr = it.effect.powerType != null ? it.effect.powerType | 0 : POWER_MANA;
+      const max = maxPowerOfType(tgt, pwr);
+      if (max > 0) setPowerOfType(tgt, pwr, Math.min(max, powerOfType(tgt, pwr) + amount));
+    }
+    spendKitItem(it, spentMap);
+    stampItemCds();
+    itemUseEvt(it.effect.kind, amount);
+    return true;
+  };
+
+  ctx.resolveItemTarget = resolveItemTarget;
+  // The item-use interrupt fires on the USER before the item's own effect runs, and every stealth and
+  // invisibility rank carries the bit. Wrapped here so one seam covers all four success returns.
+  ctx.useItem = (entry: number, targetId?: CombatantId, actor: Side = 'player'): boolean => {
+    const user = ctx.sideFighter?.(actor) ?? (actor === 'player' ? ctx.player : undefined);
+    if (user) ctx.removeAurasWithInterruptFlags?.(user, AURA_INTERRUPT.ITEM_USE, 'item use');
+    const ok = useItem(entry, targetId, actor);
+    // Off-thread the tick's `itemsSpent` lives in the WORKER, so `result().itemsConsumed` on the
+    // reading side is empty and the bags never pay. Ride it back as a recorded effect instead.
+    if (ok && (actor === 'player' || isAllySide(actor))) {
+      const bag = actor === 'player' ? ctx.playerItems : (ctx.unitItems.get(actor) ?? []);
+      const spentMap = actor === 'player'
+        ? ctx.itemsSpent
+        : (ctx.unitItemsSpent.get(actor) ?? new Map());
+      const left = bag.find((x) => x.entry === entry)?.charges;
+      emitSimEffect(ctx, {
+        kind: 'itemSpend',
+        entry,
+        total: spentMap.get(entry) ?? 0,
+        ...(left != null ? { charges: left } : {}),
+        ...(actor === 'player' ? {} : { side: actor }),
+      });
+    }
+    return ok;
+  };
+}

package/src/engine/combat/kitById.ts

@@ -0,0 +1,23 @@
+import type { SpellDef } from '../../data/schema.ts';
+
+const kitByIdCache = new WeakMap<readonly SpellDef[], Map<number, SpellDef>>();
+
+// The first row for a duplicate id, matching Array.find, keyed on the spells array so a shapeshift
+// swap misses naturally. Only for arrays replaced wholesale — a pushed-to array must use find.
+export function kitById(spells: readonly SpellDef[]): Map<number, SpellDef> {
+  let m = kitByIdCache.get(spells);
+  if (!m) {
+    m = new Map<number, SpellDef>();
+    for (const s of spells) if (!m.has(s.id)) m.set(s.id, s);
+    kitByIdCache.set(spells, m);
+  }
+  return m;
+}
+
+export function spellFromKit(
+  spells: readonly SpellDef[] | undefined,
+  id: number,
+): SpellDef | undefined {
+  if (!spells?.length) return undefined;
+  return kitById(spells).get(id);
+}

package/src/engine/combat/knockBack.ts

@@ -0,0 +1,201 @@
+// KNOCK_BACK (98) — the combat apply. Classic non-player units are a server no-op, so the geometry
+// session models the planar landing of the same ballistic trajectory instead of an intent only.
+
+import type { SpellDef } from '../../data/schema.ts';
+import type { Side } from '../core/events.ts';
+import type { CombatPosYd } from './combatGeometry.ts';
+import { combatDistanceYd } from './combatGeometry.ts';
+import { MOVEMENT_GRAVITY } from '../spells/interpreter/handlers/shared.ts';
+import { detHypot } from '../core/detMath.ts';
+import { projectWorld, type MapPct, type Viewport } from '../../world/dungeonMapProjection.ts';
+import {
+  cellOfPct,
+  lineOfSightPct,
+  snapToFloor,
+  type NavGrid,
+} from '../../world/dungeonNav.ts';
+
+/** Floorplan nav + viewport — dest is clamped on this mask, not teleported through it. */
+export type KnockBackNav = {
+  grid: NavGrid;
+  viewport: Viewport;
+};
+
+function keepLaunchZ(p: CombatPosYd, from: CombatPosYd): CombatPosYd {
+  return from.z != null && Number.isFinite(from.z) ? { x: p.x, y: p.y, z: from.z } : { x: p.x, y: p.y };
+}
+
+/** Search-grid walkable on `band`. Same lattice as dungeonNav cellOfPct. */
+function onBand(grid: NavGrid, band: number, pct: MapPct): boolean {
+  if (band < 0 || band >= grid.nBands) return false;
+  const c = cellOfPct(grid, pct);
+  if (c.x < 0 || c.y < 0 || c.x >= grid.res || c.y >= grid.res) return false;
+  return grid.cells[band * grid.res * grid.res + c.y * grid.res + c.x] === 1;
+}
+
+// Last world point on the start storey along from→dest before a blocked cell. GetHitPosition analog — stop
+// at the first hit; do not land on another storey.
+export function clampKnockBackToNav(
+  from: CombatPosYd,
+  dest: CombatPosYd,
+  nav: KnockBackNav,
+): CombatPosYd {
+  const { grid, viewport } = nav;
+  const fromPct = projectWorld(viewport, from);
+  const destPct = projectWorld(viewport, dest);
+  const start = snapToFloor(grid, { pct: fromPct, z: from.z });
+  if (!start) return keepLaunchZ(from, from);
+
+  const destSnap = snapToFloor(grid, { pct: destPct, z: from.z });
+  if (
+    onBand(grid, start.band, destPct)
+    && destSnap != null
+    && destSnap.band === start.band
+    && lineOfSightPct(grid, start.band, fromPct, destPct)
+  ) {
+    return keepLaunchZ(dest, from);
+  }
+
+  const dx = dest.x - from.x;
+  const dy = dest.y - from.y;
+  const dist = detHypot(dx, dy);
+  if (!(dist > 0)) return keepLaunchZ(from, from);
+
+  // Same half-cell fine sampling lineOfSightPct uses (dungeonNav.ts:718).
+  const fine = grid.fine.res - 1 || 1;
+  const spanYd = viewport.box[1] - viewport.box[0];
+  const stepYd = (spanYd / fine) / 2;
+  const n = Math.max(1, Math.ceil(dist / stepYd));
+  let last = keepLaunchZ(from, from);
+  for (let k = 1; k <= n; k++) {
+    const t = k / n;
+    const p = keepLaunchZ({ x: from.x + dx * t, y: from.y + dy * t }, from);
+    const pct = projectWorld(viewport, p);
+    if (!onBand(grid, start.band, pct)) break;
+    if (!lineOfSightPct(grid, start.band, fromPct, pct)) break;
+    const snap = snapToFloor(grid, { pct, z: from.z });
+    if (!snap || snap.band !== start.band) break;
+    last = p;
+  }
+  return last;
+}
+
+/** Planar yards for a knock-back with sourced horizontal/vertical speeds. */
+function knockBackDistanceYd(horizontal: number, vertical: number): number {
+  const h = Number(horizontal);
+  const v = Number(vertical);
+  if (!(h > 0) || !(v > 0) || !Number.isFinite(h) || !Number.isFinite(v)) return 0;
+  // Flat-ground flight time under constant gravity: t = 2v/g.
+  const flightTime = (2 * v) / MOVEMENT_GRAVITY;
+  if (!(flightTime > 0) || !Number.isFinite(flightTime)) return 0;
+  return h * flightTime;
+}
+
+// Push `from` away from `origin` by `distanceYd` yards (planar). When co-located, no direction exists —
+// leave position unchanged. Direction matches Unit::KnockBackFrom: caster→target angle (away from caster).
+function knockBackPosition(
+  origin: CombatPosYd,
+  from: CombatPosYd,
+  distanceYd: number,
+): CombatPosYd {
+  if (!(distanceYd > 0) || !Number.isFinite(distanceYd)) return keepLaunchZ(from, from);
+  const dx = from.x - origin.x;
+  const dy = from.y - origin.y;
+  const len = detHypot(dx, dy);
+  if (!(len > 0)) return keepLaunchZ(from, from);
+  const ux = dx / len;
+  const uy = dy / len;
+  return keepLaunchZ({ x: from.x + ux * distanceYd, y: from.y + uy * distanceYd }, from);
+}
+
+// Planar landing of a knock-back. With `nav`, dest is clamped to the last walkable cell on the start storey
+// — GetHitPosition analog, not a teleport through the wall.
+function resolveKnockBackLanding(
+  origin: CombatPosYd,
+  from: CombatPosYd,
+  distanceYd: number,
+  nav?: KnockBackNav,
+  clampLanding?: (from: CombatPosYd, dest: CombatPosYd) => CombatPosYd,
+): CombatPosYd {
+  const dest = knockBackPosition(origin, from, distanceYd);
+  if (clampLanding) return clampLanding(from, dest);
+  return nav ? clampKnockBackToNav(from, dest, nav) : dest;
+}
+
+export interface ApplyKnockBackArgs {
+  t: number;
+  spell: SpellDef;
+  /** Caster (KnockBackFrom m_caster). */
+  actor: Side;
+  /** unitTarget being pushed. */
+  target: Side;
+  horizontal: number;
+  vertical: number;
+  /** Live combat time for rootedUntil check. */
+  now: number;
+  /** Target rootedUntil (UNIT_STAT_ROOT skip). */
+  targetRootedUntil: number;
+  posOf: (side: Side | string) => CombatPosYd | undefined;
+  setPos: (side: Side | string, p: CombatPosYd) => void;
+  /** When set, landing is resolved against the instance floorplan navmask. */
+  nav?: KnockBackNav;
+  // GetHitPosition analog on the combat nav map / mesh (displaceFloor). Preferred over `nav` when both are
+  // present — the session floor is the live dungeon mask.
+  clampLanding?: (from: CombatPosYd, dest: CombatPosYd) => CombatPosYd;
+  // Drop whatever the target was walking. A landing spot is not where its corridor starts, and a stale
+  // claim would walk it straight back off the ledge it was just thrown from.
+  displaced?: (side: Side | string) => void;
+  push: (e: {
+    t: number;
+    kind: 'knock_back';
+    actor: Side;
+    target: Side;
+    spellId: number;
+    name: string;
+    horizontal: number;
+    vertical: number;
+    distanceYd: number;
+  }) => void;
+}
+
+// Apply knock-back at the combat surface, returning the distance applied — 0 when it is skipped, when
+// there is no geometry, or when both speeds are zero.
+export function applyKnockBackEffect(args: ApplyKnockBackArgs): number {
+  const {
+    t, spell, actor, target, horizontal, vertical,
+    now, targetRootedUntil, posOf, setPos, push, nav, displaced, clampLanding,
+  } = args;
+
+  // Cite: SpellEffects.cpp:5117–5118 hasUnitState(UNIT_STAT_ROOT) → return.
+  if (targetRootedUntil > now) return 0;
+
+  const distanceYd = knockBackDistanceYd(horizontal, vertical);
+  const origin = posOf(actor);
+  const from = posOf(target);
+  if (origin && from && distanceYd > 0) {
+    const next = resolveKnockBackLanding(origin, from, distanceYd, nav, clampLanding);
+    setPos(target, next);
+    displaced?.(target);
+  }
+
+  push({
+    t,
+    kind: 'knock_back',
+    actor,
+    target,
+    spellId: spell.id,
+    name: spell.name,
+    horizontal,
+    vertical,
+    distanceYd: origin && from ? distanceYd : 0,
+  });
+  return distanceYd;
+}
+
+/** Observability helper for tests — planar yards after a knock. */
+function planarKnockDeltaYd(
+  before: CombatPosYd,
+  after: CombatPosYd,
+): number {
+  return combatDistanceYd(before, after) ?? 0;
+}