@rpgm-tools/neo-angband-core 0.17.0 → 0.19.0

package/dist/combat/mon-melee.js

@@ -26,12 +26,16 @@
  * the PARALYZE damage=1 pre-clamp, and the "player moved" early-out (a blow that
  * relocates the player via earthquake / knockback skips the remaining blows).
  *
- * DEFERRED (ledgered in parity/ledger/combat-melee.yaml): monster lore /
- * smart-learn, monster-vs-monster melee (monster_attack_monster), react_to_slay
- * blocking a theft (the item is stolen regardless; no RNG impact), and attaching
- * stolen gold/items to the monster's held-object pile (monster_carry, coordinated
- * with the loot-drops gap; the item/gold is still removed from the player and no
- * RNG is drawn by the attach).
+ * All four items this header used to list as DEFERRED are ported: monster lore
+ * and smart-learn (mon/lore.ts loreLearnFlagIfVisible, project-player.ts:171),
+ * monster-vs-monster melee (game/mon-cmd.ts:317 monsterAttackMonster),
+ * react_to_slay blocking a theft on the player's pack (game/mon-side.ts:421) and
+ * attaching stolen gold/items to the thief's pile (mon/make.ts monsterCarry, used
+ * at game/known.ts:854).
+ *
+ * ONE REMAINS: the monster-vs-monster theft path does not apply react_to_slay
+ * (mon/steal.ts:234 vs mon-util.c:1548), so a slay-bearing item cannot resist
+ * being stolen by a monster from another monster. No RNG impact.
  */
 import { locEq } from "../loc.js";
 import { ELEM, MON_TMD, PROJ, RF, STAT, TMD } from "../generated/index.js";
@@ -233,153 +237,74 @@ function emitBlowMessageLive(env, ctx, reduced) {
 function drawBlowMessage(ctx) {
     displayBlowMessageVsPlayer(ctx.rng, ctx.method, 0, "", false, null);
 }
+/**
+ * `melee_handler_for_blow_effect` (mon-blows.c:1191) as a real table.
+ *
+ * Core seeds this with its 30 handlers at boot (`registerCoreBlowEffects`), so a
+ * mod can ADD a 31st effect and have `blow_effects.json`'s new record actually
+ * do something, OVERRIDE one of the 30, or WRAP one - `handlerFor` returns the
+ * handler currently installed, which is what a wrapper needs to call through to.
+ *
+ * Same shape as `EffectRegistry` deliberately: a mod author who has learned one
+ * registry in this engine has learned them all.
+ */
+export class BlowEffectRegistry {
+    handlers = new Map();
+    /** Install (or replace) the handler for an RBE_ effect name. */
+    register(name, handler) {
+        this.handlers.set(name, handler);
+    }
+    /** The handler currently installed, or null. Wrap by re-registering around it. */
+    handlerFor(name) {
+        return this.handlers.get(name) ?? null;
+    }
+    /** Whether anything answers for this effect name. */
+    has(name) {
+        return this.handlers.has(name);
+    }
+    /** Every registered effect name, in registration order. */
+    names() {
+        return [...this.handlers.keys()];
+    }
+}
+/**
+ * The registry used when a caller supplied none.
+ *
+ * This exists for the worldless harnesses and the direct-call tests, NOT as the
+ * game's registry: `wireGame` builds a fresh one per game and puts it on
+ * `GameState.blowEffects`, because a module-level singleton shared across games
+ * would let one game's mod leak into the next. A mod never reaches this one -
+ * the registry facade refuses to register when the host wired no registry, which
+ * is what stops "the mod registered and nothing read it".
+ */
+let coreFallback = null;
+function fallbackRegistry() {
+    if (coreFallback === null) {
+        coreFallback = new BlowEffectRegistry();
+        registerCoreBlowEffects(coreFallback);
+    }
+    return coreFallback;
+}
 /**
  * Resolve one RBE_ blow effect: compute the HP damage the effect deals to the
  * player (context->damage after the handler runs) and record any timed /
  * stat / inventory / elemental side-effect intents.
+ *
+ * The message draw stays HERE rather than inside the handlers.
+ * `display_blow_message_vs_player` draws `randint0(num_messages)` before
+ * take_hit in every upstream handler, so hoisting it is what keeps the stream
+ * aligned - and it means a mod's handler cannot forget it and silently shift
+ * every subsequent roll.
  */
-function resolveBlowEffect(name, ctx) {
-    const { rng, baseDamage, ac, rlev, phys } = ctx;
-    const side = [];
-    /* display_blow_message_vs_player draws randint0(num_messages) before take_hit
-     * in every handler; hoisted here for the worldless path (no-op for the single-
-     * message methods, first RNG event for the INSULT / MOAN effects). */
+function resolveBlowEffect(name, ctx, registry = fallbackRegistry()) {
     drawBlowMessage(ctx);
-    /* Elemental blows: physical component to HP; elemental component deferred. */
-    if (name === "ACID" || name === "ELEC" || name === "FIRE" || name === "COLD") {
-        const physical = phys ? adjustDamArmor(baseDamage, ac + 50) : 0;
-        side.push({
-            kind: "elemental",
-            element: ELEMENT_OF_EFFECT[name],
-            damage: baseDamage,
-        });
-        return { hpDamage: physical, obvious: true, sideEffects: side };
-    }
-    switch (name) {
-        case "NONE":
-            return { hpDamage: 0, obvious: true, sideEffects: side };
-        case "HURT":
-            return {
-                hpDamage: adjustDamArmor(baseDamage, ac),
-                obvious: true,
-                sideEffects: side,
-            };
-        case "POISON": {
-            const physical = phys ? adjustDamArmor(baseDamage, ac + 50) : 0;
-            side.push({ kind: "elemental", element: "POIS", damage: baseDamage });
-            side.push({
-                kind: "timed",
-                effect: "POISONED",
-                amount: 5 + rng.randint1(rlev),
-            });
-            return { hpDamage: physical, obvious: true, sideEffects: side };
-        }
-        case "DISENCHANT":
-            side.push({ kind: "disenchant" });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "DRAIN_CHARGES":
-            side.push({ kind: "drainCharges" });
-            return { hpDamage: baseDamage, obvious: false, sideEffects: side };
-        case "EAT_GOLD":
-            side.push({ kind: "eatGold" });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "EAT_ITEM":
-            side.push({ kind: "eatItem" });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "EAT_FOOD":
-            side.push({ kind: "eatFood" });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "EAT_LIGHT":
-            side.push({ kind: "eatLight" });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "BLIND":
-            side.push({
-                kind: "timed",
-                effect: "BLIND",
-                amount: 10 + rng.randint1(rlev),
-            });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "CONFUSE":
-            side.push({
-                kind: "timed",
-                effect: "CONFUSED",
-                amount: 3 + rng.randint1(rlev),
-            });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "TERRIFY":
-            side.push({
-                kind: "timed",
-                effect: "AFRAID",
-                amount: 3 + rng.randint1(rlev),
-            });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "PARALYZE":
-            side.push({
-                kind: "timed",
-                effect: "PARALYZED",
-                amount: 3 + rng.randint1(rlev),
-            });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "LOSE_STR":
-        case "LOSE_INT":
-        case "LOSE_WIS":
-        case "LOSE_DEX":
-        case "LOSE_CON":
-            side.push({ kind: "drainStat", stat: STAT_OF_EFFECT[name] });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "LOSE_ALL":
-            for (const stat of ["STR", "DEX", "CON", "INT", "WIS"]) {
-                side.push({ kind: "drainStat", stat });
-            }
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "SHATTER": {
-            const hp = adjustDamArmor(baseDamage, ac);
-            /* monster_damage_target() returns immediately on death (mon-blows.c
-             * L1095), before either SHATTER side-effect gate or its RNG draw. */
-            if (ctx.willPlayerDie?.(hp)) {
-                return { hpDamage: hp, obvious: true, sideEffects: side };
-            }
-            if (hp > 23) {
-                side.push({ kind: "earthquake", radius: Math.trunc(hp / 12) });
-            }
-            if (hp > 100) {
-                const value = hp - 100;
-                if (rng.randint1(value) > 40) {
-                    side.push({ kind: "knockback", distance: 1 + Math.trunc(value / 40) });
-                }
-            }
-            return { hpDamage: hp, obvious: true, sideEffects: side };
-        }
-        case "EXP_10":
-        case "EXP_20":
-        case "EXP_40":
-        case "EXP_80": {
-            const spec = EXP_DRAIN[name];
-            /* damroll(N, 6) is evaluated as the handler's argument. */
-            const amount = rng.damroll(spec.dice, 6);
-            side.push({ kind: "loseExp", holdChance: spec.holdChance, amount });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        }
-        case "HALLU":
-            side.push({
-                kind: "timed",
-                effect: "IMAGE",
-                amount: 3 + rng.randint1(Math.trunc(rlev / 2)),
-            });
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        case "BLACK_BREATH":
-            if (rng.oneIn(5)) {
-                side.push({
-                    kind: "timed",
-                    effect: "BLACKBREATH",
-                    amount: Math.trunc(baseDamage / 10),
-                });
-            }
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-        default:
-            /* Unknown effect: deal the base damage, as the fallthrough would. */
-            return { hpDamage: baseDamage, obvious: true, sideEffects: side };
-    }
+    const handler = registry.handlerFor(name);
+    if (handler !== null)
+        return handler.record(ctx);
+    /* Unknown effect: deal the base damage, as the fallthrough would. Upstream
+     * reports "ERROR: Effect handler not found" here (mon-attack.c:650); a
+     * mod-added blow_effects record with no registered handler lands on this. */
+    return { hpDamage: ctx.baseDamage, obvious: true, sideEffects: [] };
 }
 /**
  * melee_handler_for_blow_effect (mon-blows.c:1191): upstream's name -> handler
@@ -484,211 +409,406 @@ function applyElemental(env, name, ctx, pure) {
  * and context->blinked. The PARALYZE damage=1 pre-clamp is applied by the
  * caller before this runs (mon-blows.c L1020).
  */
-function resolveBlowEffectLive(name, ctx, env) {
-    const { rng, baseDamage, ac, rlev } = ctx;
-    const done = (contextDamage, reducedDamage, blinked = false) => ({ contextDamage, reducedDamage, obvious: true, blinked });
-    /* Elemental blows (pure). */
-    if (name === "ACID" || name === "ELEC" || name === "FIRE" || name === "COLD") {
-        const r = applyElemental(env, name, ctx, true);
-        return done(r.contextDamage, r.reducedDamage);
-    }
-    switch (name) {
-        case "NONE":
-            /* melee_effect_handler_NONE (mon-blows.c L638): show the message (with
-             * its randint0(num_messages) draw) for a no-damage hit; no take_hit. */
+function resolveBlowEffectLive(name, ctx, env, registry = fallbackRegistry()) {
+    const handler = registry.handlerFor(name);
+    if (handler !== null)
+        return handler.live(ctx, env);
+    /* Unknown effect: deal the base damage, as the fallthrough would. */
+    const reduced = env.applyReduction(ctx.baseDamage);
+    emitBlowMessageLive(env, ctx, reduced);
+    env.takeHit(reduced);
+    return {
+        contextDamage: ctx.baseDamage,
+        reducedDamage: reduced,
+        obvious: true,
+        blinked: false,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Core's 30 handlers
+ * ------------------------------------------------------------------ */
+/** The shape every live handler returns; `blinked` defaults false. */
+function live(contextDamage, reducedDamage, blinked = false) {
+    return { contextDamage, reducedDamage, obvious: true, blinked };
+}
+/**
+ * The damage-then-consequence sequence almost every mon-blows.c handler runs:
+ * reduce, show the message, take the hit, and do the rest only if the player
+ * survived. Factored out because it was written 20 times in the old switch and
+ * a divergence in any copy would have been invisible.
+ *
+ * `damage` is context->damage BEFORE player_apply_damage_reduction, which is
+ * what the cut/stun critical is computed from - not the HP actually lost.
+ */
+function hitThen(ctx, env, damage, after) {
+    const reduced = env.applyReduction(damage);
+    emitBlowMessageLive(env, ctx, reduced);
+    env.takeHit(reduced);
+    if (env.playerDied)
+        return live(damage, reduced);
+    return live(damage, reduced, after?.(damage) === true);
+}
+/**
+ * Seed a registry with the 30 handlers upstream ships
+ * (`melee_handler_for_blow_effect`, mon-blows.c:1197-1226).
+ *
+ * These bodies are the two switch statements this registry replaced, lifted
+ * case by case with nothing rewritten - the RNG draws sit exactly where they
+ * sat, including the places where the two paths disagree about ORDER. BLIND is
+ * the clearest: the recording path draws the message first and the duration
+ * second, the live path draws the duration first. That is a port wart, it is
+ * observable through a multi-message method like INSULT, and core keeps its
+ * warts. `blow-vectors.json` is what proves none of them moved.
+ */
+export function registerCoreBlowEffects(registry) {
+    const r = (name, handler) => registry.register(name, handler);
+    r("NONE", {
+        record: () => ({ hpDamage: 0, obvious: true, sideEffects: [] }),
+        /* melee_effect_handler_NONE (mon-blows.c L638): show the message (with its
+         * randint0(num_messages) draw) for a no-damage hit; no take_hit. */
+        live: (ctx, env) => {
             emitBlowMessageLive(env, ctx, 0);
-            return done(0, 0);
-        case "HURT": {
-            const cd = adjustDamArmor(baseDamage, ac);
-            const reduced = env.applyReduction(cd);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            return done(cd, reduced);
-        }
-        case "POISON": {
-            const r = applyElemental(env, name, ctx, false);
+            return live(0, 0);
+        },
+    });
+    r("HURT", {
+        record: (ctx) => ({
+            hpDamage: adjustDamArmor(ctx.baseDamage, ctx.ac),
+            obvious: true,
+            sideEffects: [],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, adjustDamArmor(ctx.baseDamage, ctx.ac)),
+    });
+    /* The four pure elementals. On the WORLDLESS path the physical component
+     * becomes HP damage and the elemental component is recorded as an intent; the
+     * LIVE path applies adjust_dam, inven_damage and the resist check in full
+     * through applyElemental. */
+    for (const name of ["ACID", "ELEC", "FIRE", "COLD"]) {
+        r(name, {
+            record: (ctx) => ({
+                hpDamage: ctx.phys ? adjustDamArmor(ctx.baseDamage, ctx.ac + 50) : 0,
+                obvious: true,
+                sideEffects: [
+                    {
+                        kind: "elemental",
+                        element: ELEMENT_OF_EFFECT[name],
+                        damage: ctx.baseDamage,
+                    },
+                ],
+            }),
+            live: (ctx, env) => {
+                const res = applyElemental(env, name, ctx, true);
+                return live(res.contextDamage, res.reducedDamage);
+            },
+        });
+    }
+    r("POISON", {
+        record: (ctx) => ({
+            hpDamage: ctx.phys ? adjustDamArmor(ctx.baseDamage, ctx.ac + 50) : 0,
+            obvious: true,
+            sideEffects: [
+                { kind: "elemental", element: "POIS", damage: ctx.baseDamage },
+                {
+                    kind: "timed",
+                    effect: "POISONED",
+                    amount: 5 + ctx.rng.randint1(ctx.rlev),
+                },
+            ],
+        }),
+        live: (ctx, env) => {
+            const res = applyElemental(env, "POISON", ctx, false);
             if (!env.playerDied) {
                 /* player_inc_timed(TMD_POISONED, 5 + randint1(rlev)). */
-                env.incTimed(TMD.POISONED, 5 + rng.randint1(rlev), true);
+                env.incTimed(TMD.POISONED, 5 + ctx.rng.randint1(ctx.rlev), true);
             }
-            return done(r.contextDamage, r.reducedDamage);
-        }
-        case "DISENCHANT": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied && !env.resists(ELEM.DISEN))
+            return live(res.contextDamage, res.reducedDamage);
+        },
+    });
+    r("DISENCHANT", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [{ kind: "disenchant" }],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => {
+            if (!env.resists(ELEM.DISEN))
                 env.disenchant();
-            return done(baseDamage, reduced);
-        }
-        case "DRAIN_CHARGES": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.drainCharges(rlev);
-            return done(baseDamage, reduced);
-        }
-        case "EAT_GOLD": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (env.playerDied)
-                return done(baseDamage, reduced);
-            const blinked = env.eatGold();
-            return done(baseDamage, reduced, blinked);
-        }
-        case "EAT_ITEM": {
-            /* monster_damage_target(context, false): returns only on death. */
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (env.playerDied)
-                return done(baseDamage, reduced);
-            const r = env.eatItem();
-            return done(baseDamage, reduced, r.blinked);
-        }
-        case "EAT_FOOD": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.eatFood();
-            return done(baseDamage, reduced);
-        }
-        case "EAT_LIGHT": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.eatLight();
-            return done(baseDamage, reduced);
-        }
-        case "BLIND": {
-            /* melee_effect_timed: duration arg drawn first, then damage, no save. */
-            const amount = 10 + rng.randint1(rlev);
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.incTimed(TMD.BLIND, amount, true);
-            return done(baseDamage, reduced);
-        }
-        case "CONFUSE": {
-            const amount = 3 + rng.randint1(rlev);
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.incTimed(TMD.CONFUSED, amount, true);
-            return done(baseDamage, reduced);
-        }
-        case "TERRIFY": {
-            const amount = 3 + rng.randint1(rlev);
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied) {
-                if (env.saveVsSkill())
-                    env.msg("You stand your ground!");
+        }),
+    });
+    r("DRAIN_CHARGES", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: false,
+            sideEffects: [{ kind: "drainCharges" }],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => env.drainCharges(ctx.rlev)),
+    });
+    r("EAT_GOLD", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [{ kind: "eatGold" }],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => env.eatGold()),
+    });
+    r("EAT_ITEM", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [{ kind: "eatItem" }],
+        }),
+        /* monster_damage_target(context, false): returns only on death. */
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => env.eatItem().blinked),
+    });
+    r("EAT_FOOD", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [{ kind: "eatFood" }],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => env.eatFood()),
+    });
+    r("EAT_LIGHT", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [{ kind: "eatLight" }],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => env.eatLight()),
+    });
+    /* melee_effect_timed: the duration argument is drawn BEFORE the damage on the
+     * live path, and AFTER the message on the recording path. Two of these take a
+     * saving throw first; the other two do not. */
+    const timed = (name, intent, tmd, amount, save) => r(name, {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [{ kind: "timed", effect: intent, amount: amount(ctx) }],
+        }),
+        live: (ctx, env) => {
+            const dur = amount(ctx);
+            return hitThen(ctx, env, ctx.baseDamage, () => {
+                if (save !== undefined && env.saveVsSkill())
+                    env.msg(save);
                 else
-                    env.incTimed(TMD.AFRAID, amount, true);
-            }
-            return done(baseDamage, reduced);
-        }
-        case "PARALYZE": {
-            const amount = 3 + rng.randint1(rlev);
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied) {
-                if (env.saveVsSkill())
-                    env.msg("You resist the effects!");
-                else
-                    env.incTimed(TMD.PARALYZED, amount, true);
+                    env.incTimed(tmd, dur, true);
+            });
+        },
+    });
+    timed("BLIND", "BLIND", TMD.BLIND, (ctx) => 10 + ctx.rng.randint1(ctx.rlev));
+    timed("CONFUSE", "CONFUSED", TMD.CONFUSED, (ctx) => 3 + ctx.rng.randint1(ctx.rlev));
+    timed("TERRIFY", "AFRAID", TMD.AFRAID, (ctx) => 3 + ctx.rng.randint1(ctx.rlev), "You stand your ground!");
+    timed("PARALYZE", "PARALYZED", TMD.PARALYZED, (ctx) => 3 + ctx.rng.randint1(ctx.rlev), "You resist the effects!");
+    for (const name of ["LOSE_STR", "LOSE_INT", "LOSE_WIS", "LOSE_DEX", "LOSE_CON"]) {
+        r(name, {
+            record: (ctx) => ({
+                hpDamage: ctx.baseDamage,
+                obvious: true,
+                sideEffects: [{ kind: "drainStat", stat: STAT_OF_EFFECT[name] }],
+            }),
+            live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => env.drainStat(STAT_OF_LIVE_EFFECT[name])),
+        });
+    }
+    r("LOSE_ALL", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            /* Upstream's order here is STR, DEX, CON, INT, WIS - not the STAT order. */
+            sideEffects: ["STR", "DEX", "CON", "INT", "WIS"].map((stat) => ({
+                kind: "drainStat",
+                stat,
+            })),
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => {
+            env.drainStat(STAT.STR);
+            env.drainStat(STAT.DEX);
+            env.drainStat(STAT.CON);
+            env.drainStat(STAT.INT);
+            env.drainStat(STAT.WIS);
+        }),
+    });
+    r("SHATTER", {
+        record: (ctx) => {
+            const hp = adjustDamArmor(ctx.baseDamage, ctx.ac);
+            const side = [];
+            /* monster_damage_target() returns immediately on death (mon-blows.c
+             * L1095), before either SHATTER side-effect gate or its RNG draw. */
+            if (ctx.willPlayerDie?.(hp)) {
+                return { hpDamage: hp, obvious: true, sideEffects: side };
             }
-            return done(baseDamage, reduced);
-        }
-        case "LOSE_STR":
-        case "LOSE_INT":
-        case "LOSE_WIS":
-        case "LOSE_DEX":
-        case "LOSE_CON": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.drainStat(STAT_OF_LIVE_EFFECT[name]);
-            return done(baseDamage, reduced);
-        }
-        case "LOSE_ALL": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied) {
-                env.drainStat(STAT.STR);
-                env.drainStat(STAT.DEX);
-                env.drainStat(STAT.CON);
-                env.drainStat(STAT.INT);
-                env.drainStat(STAT.WIS);
+            if (hp > 23)
+                side.push({ kind: "earthquake", radius: Math.trunc(hp / 12) });
+            if (hp > 100) {
+                const value = hp - 100;
+                if (ctx.rng.randint1(value) > 40) {
+                    side.push({ kind: "knockback", distance: 1 + Math.trunc(value / 40) });
+                }
             }
-            return done(baseDamage, reduced);
-        }
-        case "SHATTER": {
-            const cd = adjustDamArmor(baseDamage, ac);
-            const reduced = env.applyReduction(cd);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (env.playerDied)
-                return done(cd, reduced);
+            return { hpDamage: hp, obvious: true, sideEffects: side };
+        },
+        live: (ctx, env) => hitThen(ctx, env, adjustDamArmor(ctx.baseDamage, ctx.ac), (cd) => {
             if (cd > 23)
                 env.earthquake(Math.trunc(cd / 12));
             if (cd > 100) {
                 const value = cd - 100;
-                if (rng.randint1(value) > 40)
+                if (ctx.rng.randint1(value) > 40)
                     env.thrust(1 + Math.trunc(value / 40));
             }
-            return done(cd, reduced);
-        }
-        case "EXP_10":
-        case "EXP_20":
-        case "EXP_40":
-        case "EXP_80": {
-            const spec = EXP_DRAIN[name];
-            /* damroll(N, 6) is evaluated as the handler's argument, before take_hit. */
-            const drainAmount = rng.damroll(spec.dice, 6);
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied)
-                env.drainExp(spec.holdChance, drainAmount);
-            return done(baseDamage, reduced);
-        }
-        case "HALLU": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied) {
-                env.incTimed(TMD.IMAGE, 3 + rng.randint1(Math.trunc(rlev / 2)), true);
+        }),
+    });
+    for (const name of ["EXP_10", "EXP_20", "EXP_40", "EXP_80"]) {
+        const spec = EXP_DRAIN[name];
+        r(name, {
+            record: (ctx) => ({
+                hpDamage: ctx.baseDamage,
+                obvious: true,
+                /* damroll(N, 6) is evaluated as the handler's argument. */
+                sideEffects: [
+                    {
+                        kind: "loseExp",
+                        holdChance: spec.holdChance,
+                        amount: ctx.rng.damroll(spec.dice, 6),
+                    },
+                ],
+            }),
+            live: (ctx, env) => {
+                /* ...which on the live path means BEFORE take_hit. */
+                const drainAmount = ctx.rng.damroll(spec.dice, 6);
+                return hitThen(ctx, env, ctx.baseDamage, () => env.drainExp(spec.holdChance, drainAmount));
+            },
+        });
+    }
+    r("HALLU", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: [
+                {
+                    kind: "timed",
+                    effect: "IMAGE",
+                    amount: 3 + ctx.rng.randint1(Math.trunc(ctx.rlev / 2)),
+                },
+            ],
+        }),
+        /* Unlike the other timed blows, HALLU draws its duration AFTER take_hit. */
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => {
+            env.incTimed(TMD.IMAGE, 3 + ctx.rng.randint1(Math.trunc(ctx.rlev / 2)), true);
+        }),
+    });
+    r("BLACK_BREATH", {
+        record: (ctx) => ({
+            hpDamage: ctx.baseDamage,
+            obvious: true,
+            sideEffects: ctx.rng.oneIn(5)
+                ? [
+                    {
+                        kind: "timed",
+                        effect: "BLACKBREATH",
+                        amount: Math.trunc(ctx.baseDamage / 10),
+                    },
+                ]
+                : [],
+        }),
+        live: (ctx, env) => hitThen(ctx, env, ctx.baseDamage, () => {
+            if (ctx.rng.oneIn(5)) {
+                env.incTimed(TMD.BLACKBREATH, Math.trunc(ctx.baseDamage / 10), false);
             }
-            return done(baseDamage, reduced);
-        }
-        case "BLACK_BREATH": {
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            if (!env.playerDied && rng.oneIn(5)) {
-                env.incTimed(TMD.BLACKBREATH, Math.trunc(baseDamage / 10), false);
+        }),
+    });
+}
+/**
+ * Build a handler from a spec, so a mod writes its effect once.
+ *
+ * The live half applies each described side effect through the env with
+ * `applyBlowSideEffect`, which is the same vocabulary the worldless path
+ * records. A mod that describes "poison the player for 2d6 turns" therefore
+ * gets a recorded intent in the harness and a real `player_inc_timed` in the
+ * game, from one line, with no chance of the two disagreeing.
+ */
+export function blowEffect(spec) {
+    const damageOf = (ctx) => spec.damage ? spec.damage(ctx) : ctx.baseDamage;
+    const obvious = spec.obvious ?? true;
+    return {
+        record: (ctx) => {
+            const damage = damageOf(ctx);
+            const before = spec.before ? [...spec.before(ctx)] : [];
+            /* The worldless path has no HP model of its own, so "did the player
+             * survive" is the caller's willPlayerDie, the same gate SHATTER uses. */
+            const died = ctx.willPlayerDie?.(damage) === true;
+            const after = died || !spec.after ? [] : [...spec.after(ctx)];
+            return { hpDamage: damage, obvious, sideEffects: [...before, ...after] };
+        },
+        live: (ctx, env) => {
+            const damage = damageOf(ctx);
+            const before = spec.before ? [...spec.before(ctx)] : [];
+            const result = hitThen(ctx, env, damage, () => {
+                let blinked = false;
+                for (const effect of [...before, ...(spec.after?.(ctx) ?? [])]) {
+                    if (applyBlowSideEffect(env, effect))
+                        blinked = true;
+                    if (env.playerDied)
+                        break;
+                }
+                return blinked;
+            });
+            return { ...result, obvious };
+        },
+    };
+}
+/**
+ * Apply one recorded side-effect intent to the world. Returns whether it blinked
+ * the monster away (context->blinked), which only the two thefts do.
+ *
+ * This is what makes `BlowSideEffect` a shared VOCABULARY rather than a
+ * worldless-only log: the same value that gets recorded in the harness is the
+ * one that gets applied in the game.
+ */
+export function applyBlowSideEffect(env, effect) {
+    switch (effect.kind) {
+        case "timed": {
+            const tmd = TMD[effect.effect];
+            if (tmd !== undefined)
+                env.incTimed(tmd, effect.amount, true);
+            return false;
+        }
+        case "drainStat": {
+            const stat = STAT[effect.stat];
+            if (stat !== undefined)
+                env.drainStat(stat);
+            return false;
+        }
+        case "loseExp":
+            env.drainExp(effect.holdChance, effect.amount);
+            return false;
+        case "drainCharges":
+            env.drainCharges(0);
+            return false;
+        case "eatGold":
+            return env.eatGold();
+        case "eatItem":
+            return env.eatItem().blinked;
+        case "eatFood":
+            env.eatFood();
+            return false;
+        case "eatLight":
+            env.eatLight();
+            return false;
+        case "disenchant":
+            env.disenchant();
+            return false;
+        case "elemental": {
+            const elem = ELEM[effect.element];
+            if (elem !== undefined) {
+                env.invenDamage(elem, Math.min(effect.damage * 5, 300));
             }
-            return done(baseDamage, reduced);
-        }
-        default: {
-            /* Unknown effect: deal the base damage, as the fallthrough would. */
-            const reduced = env.applyReduction(baseDamage);
-            emitBlowMessageLive(env, ctx, reduced);
-            env.takeHit(reduced);
-            return done(baseDamage, reduced);
-        }
+            return false;
+        }
+        case "earthquake":
+            env.earthquake(effect.radius);
+            return false;
+        case "knockback":
+            env.thrust(effect.distance);
+            return false;
     }
 }
 /* ------------------------------------------------------------------ *
@@ -739,6 +859,10 @@ export function monMeleeAttack(rng, mon, defender, def, opts = {}) {
             /* Visible monster missed the player: announce it (mon-attack.c L718). No
              * RNG is drawn; unseen monsters and no-miss methods stay silent. */
             if (env && env.monVisible && blow.method.miss) {
+                /* disturb(p) before the line (mon-attack.c L719-721): a MISS the player
+                 * can see is still news, and stops a run or a rest. Nothing here reduces
+                 * HP, so take_hit's own disturb cannot stand in for it. */
+                env.disturb?.();
                 env.msg(`${env.monName} misses you.`);
             }
             blows.push({
@@ -751,6 +875,13 @@ export function monMeleeAttack(rng, mon, defender, def, opts = {}) {
             });
             continue;
         }
+        /* "Always disturbing" (mon-attack.c L593-594): the blow CONNECTED, so the
+         * player is disturbed before anything else happens - before protection from
+         * evil, before the damage roll, and regardless of whether the blow ends up
+         * doing any damage at all. take_hit's disturb (player-util.c:207) covers only
+         * the damaging blows; a 0-damage effect blow like BLIND or a repelled evil
+         * monster is disturbing here and nowhere else. */
+        env?.disturb?.();
         /* Apply "protection from evil" (mon-attack.c L597): an evil monster is
          * repelled on a high roll. The randint0(100) draw happens only when the
          * guard conditions hold, matching the C short-circuit order. */
@@ -795,7 +926,7 @@ export function monMeleeAttack(rng, mon, defender, def, opts = {}) {
         let obvious;
         const blowSide = [];
         if (env) {
-            const res = resolveBlowEffectLive(effectName, blowCtx, env);
+            const res = resolveBlowEffectLive(effectName, blowCtx, env, opts.blowEffects);
             contextDamage = res.contextDamage;
             dealtDamage = res.reducedDamage;
             obvious = res.obvious;
@@ -807,7 +938,7 @@ export function monMeleeAttack(rng, mon, defender, def, opts = {}) {
                 playerDied = true;
         }
         else {
-            const res = resolveBlowEffect(effectName, blowCtx);
+            const res = resolveBlowEffect(effectName, blowCtx, opts.blowEffects);
             contextDamage = res.hpDamage;
             dealtDamage = res.hpDamage;
             obvious = res.obvious;