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

package/dist/game/player-side-vectors.js

@@ -0,0 +1,292 @@
+/**
+ * Golden vectors for project_p: what EVERY projection does to the PLAYER,
+ * recorded from the code BEFORE the dispatch switch became a registry.
+ *
+ * WHY A RECORDING AND NOT "THE TESTS STILL PASS". player-side.test.ts asserts
+ * particular behaviours - SHARD cuts, PROT_STUN blocks a SOUND stun, a resisted
+ * breath still teaches its rune - and those were written to pin the bugs they
+ * were found by, not the cross product. Converting a 21-case switch over
+ * faithful behaviour to a registry buys moddability and nothing else, so the
+ * standard is "nothing moved", and only a recording of the producer can say so.
+ *
+ * WHAT A SCENARIO CAPTURES. project_p is the widest-reaching of the three
+ * projection handlers: it damages the pack, drains stats and experience, sets
+ * nine timed effects, disenchants worn gear, spends mana and energy, and
+ * teleports the player outright. So the snapshot is broad on purpose - every
+ * message in order, the extra damage returned, the whole timed array, both stat
+ * arrays, exp / mana / energy, where the player ended up, and what is left of
+ * the pack and the worn armour.
+ *
+ * AND THE RNG POSITION. `rngProbe` is one draw taken after the scenario. Two
+ * implementations can agree on every visible value while drawing a different
+ * NUMBER of randoms, and here that is not hypothetical: FIRE, COLD, DARK,
+ * NETHER and POIS all roll `randint0(dam)` and then decide, TIME picks a branch
+ * with two draws before doing anything, and POIS's acid sting runs adjust_dam,
+ * which evaluates a dice denominator. Every one of those is invisible in the
+ * result and diverges the whole game a few turns later.
+ *
+ * The fixtures are INJECTED (`PlayerSideFixtures`) so this module needs no
+ * node:fs and stays importable anywhere; the one copy that reads the disk is
+ * `player-side-vectors.fixtures.ts`, shared by the test and the generator so
+ * they cannot disagree about what they are measuring.
+ */
+import { ELEM, PROJ, TMD } from "../generated/index.js";
+import { loc } from "../loc.js";
+import { makePlayerSideEffects } from "./player-side.js";
+/**
+ * The projections worth recording: every arm of the switch, plus three that
+ * fall to the empty default. The default group is sampled rather than
+ * enumerated because the vectors would then be measuring `PROJ`'s size rather
+ * than project_p's behaviour - its membership is asserted separately by the
+ * coverage guard in the test.
+ */
+export const VECTOR_PROJECTIONS = [
+    ["ACID", PROJ.ACID],
+    ["ELEC", PROJ.ELEC],
+    ["FIRE", PROJ.FIRE],
+    ["COLD", PROJ.COLD],
+    ["POIS", PROJ.POIS],
+    ["LIGHT", PROJ.LIGHT],
+    ["DARK", PROJ.DARK],
+    ["DARK_WEAK", PROJ.DARK_WEAK],
+    ["SOUND", PROJ.SOUND],
+    ["SHARD", PROJ.SHARD],
+    ["NEXUS", PROJ.NEXUS],
+    ["NETHER", PROJ.NETHER],
+    ["CHAOS", PROJ.CHAOS],
+    ["DISEN", PROJ.DISEN],
+    ["WATER", PROJ.WATER],
+    ["ICE", PROJ.ICE],
+    ["GRAVITY", PROJ.GRAVITY],
+    ["INERTIA", PROJ.INERTIA],
+    ["FORCE", PROJ.FORCE],
+    ["TIME", PROJ.TIME],
+    ["PLASMA", PROJ.PLASMA],
+    /* The empty-handler group: no player side effect at all. */
+    ["METEOR", PROJ.METEOR],
+    ["MISSILE", PROJ.MISSILE],
+    ["MANA", PROJ.MANA],
+];
+/**
+ * Damage values. The `randint0(dam) > 500` gates in FIRE, COLD and DARK cannot
+ * fire below 501 at all, so a grid that only ran small hits would record the
+ * powerful-attack arms as dead code. 5000 clears every threshold in the file.
+ */
+export const VECTOR_DAMAGE = [10, 5000];
+/**
+ * Monster spell power. The bonus arms gate on >= 60 (POIS), >= 70 (DARK) and
+ * >= 80 (FIRE, COLD, NETHER); 0 is below all of them and 80 is above all.
+ */
+export const VECTOR_POWER = [0, 80];
+/**
+ * res_level the projection actor reports for EVERY element. 3 is immunity,
+ * which is what ACID / ELEC / FIRE / COLD / ICE check before touching the pack;
+ * 1 is the plain resist that makes nine handlers bail with "You resist the
+ * effect!" - and those early breaks are exactly what a mis-keyed registry would
+ * skip.
+ */
+export const VECTOR_RESISTS = [
+    ["none", 0],
+    ["resist", 1],
+    ["immune", 3],
+];
+/**
+ * The seeds the grid runs.
+ *
+ * SIX, NOT TWO, and the reason is worth keeping. Seven handlers ignore `power`
+ * and NEXUS ignores `dam` as well, so for those the whole rest of the grid
+ * collapses onto ONE rng stream per seed - two seeds gave NEXUS four distinct
+ * paths and its 1-in-4 teleport-level arm came up empty in all 96 of its rows.
+ * A dimension that does not vary the handler's input does not sample it.
+ */
+export const VECTOR_SEEDS = [1, 7, 16, 29, 43, 61];
+/** Where a monster-sourced projection comes from: away from the player. */
+const CASTER_GRID = loc(7, 7);
+/** Name by index for a TMD value, so a vector reads as an effect not a number. */
+function timedName(idx) {
+    for (const [name, value] of Object.entries(TMD)) {
+        if (value === idx)
+            return name;
+    }
+    return `TMD_${String(idx)}`;
+}
+/**
+ * A stub projection actor reporting one res_level for every element.
+ *
+ * FLAT ON PURPOSE. Per-element resist profiles would multiply the grid by the
+ * element count to separate handlers that are already separated by `proj`; what
+ * the vectors need is that each handler's resisted and unresisted arms are both
+ * reached, and one level applied to all elements does that in three rows.
+ */
+function stubActor(level, energyRef) {
+    return {
+        resistLevel: () => level,
+        get energy() {
+            return energyRef.value;
+        },
+        set energy(v) {
+            energyRef.value = v;
+        },
+    };
+}
+/**
+ * Run one scenario and record it.
+ *
+ * Built fresh from a seeded state each time, so a vector is a function of its
+ * own inputs alone - no ordering between rows, which is what lets one `it()`
+ * per row report a divergence by name.
+ */
+export function recordPlayerSide(fx, projName, proj, dam, power, resistName, resistLevel, warded, originName, seed) {
+    const state = fx.makeState(seed);
+    const p = state.actor.player;
+    /* A level and an experience total, because four handlers drain experience and
+     * a level-1 player with 0 exp records every drain as a no-op. GRAVITY's blink
+     * also compares randint1(127) against p->lev. */
+    p.lev = 20;
+    p.exp = 50_000;
+    p.maxExp = 50_000;
+    p.msp = 40;
+    p.csp = 40;
+    /* Stats above the floor, so a drain has somewhere to go. */
+    for (let i = 0; i < p.statCur.length; i++) {
+        p.statCur[i] = 15;
+        p.statMax[i] = 15;
+    }
+    fx.equipArmour(state, warded);
+    fx.fillPack(state);
+    const monsterIdx = originName === "monster" ? fx.addMonster(state, CASTER_GRID) : 0;
+    const messages = [];
+    /* state.actor.energy is a live field on the harness actor; the stub reads and
+     * writes THROUGH it so NETHER's "Your energy is sapped!" stays observable. */
+    const energyRef = { value: 100 };
+    state.actor.energy = 100;
+    /* The teleport seams GRAVITY, NEXUS and FORCE reach through. Recorded rather
+     * than omitted: `changeLevel` is the ONLY observable half of NEXUS's
+     * teleport-level arm - the harness has no session to change level for - and
+     * without it that arm looks identical to a no-op. */
+    let levelChangeTo = null;
+    let postMoves = 0;
+    const deps = {
+        timed: fx.timed,
+        actor: stubActor(resistLevel, energyRef),
+        projections: fx.projections,
+        expDeps: { rng: state.rng },
+        lifeDrainPercent: 2,
+        teleport: {
+            changeLevel: (depth) => {
+                levelChangeTo = depth;
+            },
+            onPlayerPostMove: () => {
+                postMoves++;
+            },
+        },
+        msg: (t) => messages.push(t),
+    };
+    const hook = makePlayerSideEffects(state, deps);
+    const xtra = hook({
+        origin: originName === "monster"
+            ? {
+                isPlayer: false,
+                isMonster: true,
+                monster: monsterIdx,
+                grid: CASTER_GRID,
+                killer: "a recorded caster",
+            }
+            : {
+                isPlayer: false,
+                isMonster: false,
+                isTrap: true,
+                /* On the player's OWN grid: FORCE's trap arm reads exactly that,
+                 * and pushes them in a random direction when it holds. */
+                grid: state.actor.grid,
+                killer: "a recorded trap",
+            },
+        r: 0,
+        grid: state.actor.grid,
+        dam,
+        typ: proj,
+        power,
+        obvious: true,
+    });
+    const timedOn = [];
+    for (let i = 0; i < p.timed.length; i++) {
+        if ((p.timed[i] ?? 0) > 0)
+            timedOn.push(`${timedName(i)}=${String(p.timed[i])}`);
+    }
+    let packItems = 0;
+    for (const handle of state.gear.pack) {
+        packItems += state.gear.store.get(handle)?.number ?? 0;
+    }
+    let gearEnchant = 0;
+    for (const handle of [...state.gear.pack, ...p.equipment]) {
+        const obj = state.gear.store.get(handle);
+        if (obj)
+            gearEnchant += obj.toH + obj.toD + obj.toA;
+    }
+    return {
+        id: `${projName}/dam${String(dam)}/pow${String(power)}/${resistName}` +
+            `/${warded ? "warded" : "bare"}/${originName}/seed${String(seed)}`,
+        proj: projName,
+        dam,
+        power,
+        resist: resistName,
+        warded,
+        origin: originName,
+        seed,
+        xtra,
+        messages,
+        timed: timedOn.sort(),
+        statCur: [...p.statCur],
+        statMax: [...p.statMax],
+        exp: p.exp,
+        maxExp: p.maxExp,
+        csp: p.csp,
+        energy: state.actor.energy,
+        grid: [state.actor.grid.x, state.actor.grid.y],
+        levelChangeTo,
+        postMoves,
+        packStacks: state.gear.pack.length,
+        packItems,
+        gearEnchant,
+        /* Nearly every arm teaches a rune - the sustains, HOLD_LIFE, PROT_STUN -
+         * and equip_learn_flag is a real side effect upstream performs whether or
+         * not the effect landed. Counting them makes a dropped learn visible. */
+        learnedFlags: p.objKnown.flags.count(),
+        /* Capped well under Rand_div's 0x10000000 limit. */
+        rngProbe: state.rng.randint0(100_000_000),
+    };
+}
+/** Every scenario in the grid, in a fixed order. */
+export function recordAllPlayerSide(fx) {
+    const out = [];
+    for (const [projName, proj] of VECTOR_PROJECTIONS) {
+        for (const dam of VECTOR_DAMAGE) {
+            for (const power of VECTOR_POWER) {
+                for (const [resistName, resistLevel] of VECTOR_RESISTS) {
+                    for (const warded of [false, true]) {
+                        for (const originName of ["monster", "trap"]) {
+                            for (const seed of VECTOR_SEEDS) {
+                                out.push(recordPlayerSide(fx, projName, proj, dam, power, resistName, resistLevel, warded, originName, seed));
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+/** The elements whose immunity gates a pack-damage arm, for the coverage guard. */
+export const PACK_DAMAGE_ELEMENTS = [
+    ELEM.ACID,
+    ELEM.ELEC,
+    ELEM.FIRE,
+    ELEM.COLD,
+];
+/**
+ * The dungeon depth every scenario runs at. Not incidental: the harness builds
+ * at depth 0, the TOWN, and teleport_player_level cannot go up from there - so
+ * its up/down coin flip, a real RNG draw, never happened on the first pass.
+ */
+export const VECTOR_DEPTH = 5;
+//# sourceMappingURL=player-side-vectors.js.map

package/dist/game/player-side-vectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player-side-vectors.js","sourceRoot":"","sources":["../../src/game/player-side-vectors.ts"],"names":[],"mappings":"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"}

package/dist/game/player-side.d.ts

@@ -22,11 +22,33 @@
  * distinct: drainStat is effect_simple(EF_DRAIN_STAT) (sustain saves with the
  * "You feel very %s..." messages), drainStatsRandom is
  * project_player_drain_stats (no sustain, always "You're not as %s...").
+ *
+ * THE DISPATCH IS A REGISTRY, as of 2026-08-09. It was a 21-case switch, and
+ * the last of the three - project_f's 37 and project_o's 11 were converted the
+ * day before, so a mod's projection reached terrain and objects but not the
+ * player, which is the half that matters. PLAYER_SIDE_HANDLERS is keyed by
+ * projection CODE exactly as the other two are, and `deps.playerHandlers` is
+ * the table the game actually dispatches through - supplied by wireGame from
+ * the per-game ProjectionHandlerRegistry (game/projection-handlers.ts), which a
+ * mod writes one code at a time through "registry:projection".
+ *
+ * What made this one a real refactor rather than a mechanical lift: the arms
+ * read ten helpers built per game, and `incCheck` reads a `currentSource`
+ * stamped per PROJECTION. `PlayerSideCtx` is those helpers made explicit, which
+ * is what lets the arms be ordinary top-level functions.
+ *
+ * The 6,912 vectors in player-side-vectors.json were recorded from the SWITCH
+ * and are replayed against the table, because the conversion bought moddability
+ * and was required to change nothing else - including the number of rng draws,
+ * which no visible value would have shown.
  */
 import type { ProjectionInfo } from "../world/projection.js";
 import type { TimedEffect } from "../player/types.js";
-import type { PlayerIncCheckQueries } from "../player/timed.js";
+import type { PlayerIncCheckHooks, PlayerIncCheckQueries, TimedNotifyQueries } from "../player/timed.js";
+import type { Monster } from "../mon/monster.js";
+import type { Player } from "../player/player.js";
 import type { ExpDeps } from "../player/exp.js";
+import type { Rng } from "../rng.js";
 import type { GameState } from "./context.js";
 import type { PlayerProjActor, ProjectPlayerSideContext } from "./project-player.js";
 import type { TeleportEnv } from "./effect-teleport.js";
@@ -39,6 +61,92 @@ import type { TeleportEnv } from "./effect-teleport.js";
  * the timed check reads the live duration array.
  */
 export declare function makeIncCheckQueries(state: GameState): PlayerIncCheckQueries;
+/**
+ * makeTimedNotifyQueries: the obj_k reads player_set_timed's notify suppression
+ * needs (player-timed.c:828-839).
+ *
+ * "Don't mention effects which already match the known player state" - a
+ * temporary resist you are KNOWN to be immune to, or a flag synonym you are
+ * KNOWN to have from worn gear. It silences a message and never changes the
+ * duration, which is why it went unnoticed: nothing supplied these queries in
+ * production, so every such effect announced itself.
+ *
+ * hasFlagNotTimed is player_of_has_not_timed (player-timed.c:747-763): the
+ * player's own flags UNION every equipped object's, deliberately WITHOUT timed
+ * effects - that exclusion is the whole point of the predicate.
+ */
+export declare function makeTimedNotifyQueries(state: GameState): TimedNotifyQueries;
+/**
+ * makeIncCheckHooks: player_inc_check's SIDE EFFECTS over the live state
+ * (player-timed.c:945-953 for object flags, :967 and :985 for resists and
+ * vulnerabilities).
+ *
+ * The two equip-learn calls are UNCONDITIONAL in upstream's non-lore branch -
+ * a trap you are immune to, a potion, a monster's breath and a monster's blow
+ * all teach the rune the same way. Only update_smart_learn and the "You resist
+ * the effect!" line are gated on `cave->mon_current > 0`, which is what
+ * `monster` supplies here.
+ *
+ * Everything below is RNG-free: equipLearnFlag / equipLearnElement walk the
+ * worn slots and write knowledge (obj/knowledge.ts:773, :795), and neither they
+ * nor playerLearnFlagRune / objectCursesFindFlags draw. That was measured
+ * rather than assumed, because supplying these on paths that previously had no
+ * hooks would otherwise move the RNG stream under every seeded test.
+ */
+export declare function makeIncCheckHooks(state: GameState, opts?: {
+    /** The message sink for "You resist the effect!" (monster sources only). */
+    msg?: (text: string) => void;
+    /** cave->mon_current: the acting monster, when one is acting. */
+    monster?: Monster | null;
+}): PlayerIncCheckHooks;
+/**
+ * What one per-projection player handler is handed: the projection being
+ * resolved, and the toolkit the arms used to close over.
+ *
+ * THE TOOLKIT IS THE WHOLE REASON THIS TYPE EXISTS. project_f's and project_o's
+ * handlers took (state, grid, dam) and a bag of env, so lifting them to module
+ * level was mechanical. project_p's arms read ten helpers built per game -
+ * player_inc_timed bound to the timed registry, player_inc_check bound to the
+ * live derived state, the two distinct stat drains, the HOLD_LIFE life drain -
+ * and one of them, `incCheck`, reads a `currentSource` that is stamped per
+ * PROJECTION. Passing those in explicitly is what lets the arms below be
+ * ordinary top-level functions, and lets a mod supply its own.
+ */
+export interface PlayerSideCtx {
+    readonly state: GameState;
+    readonly deps: PlayerSideDeps;
+    /** The upstream handler context: origin, grid, typ, power, obvious. */
+    readonly proj: ProjectPlayerSideContext;
+    /** context->dam, which nine arms scale their effects off. */
+    readonly dam: number;
+    /** Monster spell power: the >= 60 / 70 / 80 gates on the bonus arms. */
+    readonly power: number;
+    readonly rng: Rng;
+    /** The player, so an arm does not spell out state.actor.player every line. */
+    p(): Player;
+    msg(text: string): void;
+    /** player_inc_timed through the bound registry. */
+    incTimed(idx: number, v: number, check: boolean): boolean;
+    /** player_inc_check as a pure predicate, for the pre-message resist test. */
+    incCheck(idx: number): boolean;
+    /** el_info[elem].res_level === 3. */
+    isImmune(elem: number): boolean;
+    /** el_info[elem].res_level > 0. */
+    resists(elem: number): boolean;
+    /** effect_simple(EF_DRAIN_STAT): the sustain saves it. */
+    drainStat(stat: number): void;
+    /** project_player_drain_stats(num): no sustain, always the message. */
+    drainStatsRandom(num: number): void;
+    /** Experience drain with the HOLD_LIFE gate. */
+    drainLife(amount: number, text: string): void;
+    /**
+     * Extra damage applied after damage reduction. Mutable and written in place,
+     * exactly as `ProjectObjCtx.out` is - POIS's acid sting is the only writer.
+     */
+    xtra: number;
+}
+/** One projection's side effects on the player. Writes `ctx.xtra` if any. */
+export type PlayerSideHandler = (ctx: PlayerSideCtx) => void;
 /** Everything the side-effect handlers need beyond the GameState. */
 export interface PlayerSideDeps {
     /** The bound timed-effect registry (players.timed), TMD-indexed. */
@@ -53,7 +161,27 @@ export interface PlayerSideDeps {
     lifeDrainPercent: number;
     /** The teleport seams (no-teleport curse, post-move) for GRAVITY's blink. */
     teleport?: TeleportEnv;
+    /**
+     * The player-handler table to dispatch through, defaulting to
+     * PLAYER_SIDE_HANDLERS. Supplied by wireGame from
+     * `GameState.projectionHandlers`, by identity, exactly as `featHandlers` and
+     * `objHandlers` are - see game/projection-handlers.ts.
+     */
+    playerHandlers?: ReadonlyMap<string, PlayerSideHandler>;
     msg?(text: string): void;
 }
+/**
+ * project_player_handler_f[]: the per-projection player side effects, keyed by
+ * projection CODE.
+ *
+ * KEYED BY CODE, NOT BY PROJ VALUE, and the same way project_f's and
+ * project_o's tables are. A mod's own projection is appended to the bound
+ * projection table at a slot core never compiled in, so a numeric key would put
+ * its handler somewhere nothing looks; the code is the identity that survives.
+ *
+ * A projection with NO entry does nothing to the player, which is upstream's
+ * empty handler and is why there is no default arm here to write.
+ */
+export declare const PLAYER_SIDE_HANDLERS: ReadonlyMap<string, PlayerSideHandler>;
 export declare function makePlayerSideEffects(state: GameState, deps: PlayerSideDeps): (ctx: ProjectPlayerSideContext) => number;
 //# sourceMappingURL=player-side.d.ts.map

package/dist/game/player-side.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"player-side.d.ts","sourceRoot":"","sources":["../../src/game/player-side.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAMhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,qBAAqB,CAmB3E;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,gEAAgE;IAChE,KAAK,EAAE,eAAe,CAAC;IACvB,mEAAmE;IACnE,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IACvC,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAsCD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,cAAc,GACnB,CAAC,GAAG,EAAE,wBAAwB,KAAK,MAAM,CA6Z3C"}
+{"version":3,"file":"player-side.d.ts","sourceRoot":"","sources":["../../src/game/player-side.ts"],"names":[],"mappings":"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"}