@rpgm-tools/neo-angband-core 0.10.0

package/dist/player/spell.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Player spells, ported from reference/src/player-spell.c (Angband 4.2.6)
+ * plus the spell-related pieces of player-calcs.c (calc_mana, calc_spells,
+ * average_spell_stat) and init.c's write_book_kind (spellbook object kinds
+ * are created FROM the class book definitions, exactly as upstream does at
+ * class-parse time - object.txt carries no book kinds).
+ *
+ * This module is pure player/object domain logic: learning, fail chances,
+ * mana, book lookups. The cast itself (running a spell's effect chain
+ * against the live GameState) lives in game/spell-cmd.ts, the same split as
+ * monster spells (mon/spell.ts vs game/mon-cast.ts).
+ */
+import type { ObjRegistry } from "../obj/bind.js";
+import type { GameObject } from "../obj/object.js";
+import type { ClassBook, ClassSpell, MagicRealm, PlayerClass } from "./types.js";
+import type { Player } from "./player.js";
+/** PY_SPELL_ flags (player.h). */
+export declare const PY_SPELL: {
+    readonly LEARNED: 1;
+    readonly WORKED: 2;
+    readonly FORGOTTEN: 4;
+};
+/** Stat Table (INT/WIS) -- minimum spell failure rate (player-spell.c L49). */
+export declare const adj_mag_fail: readonly number[];
+/** Stat Table (INT/WIS) -- failure rate adjustment (player-spell.c L94). */
+export declare const adj_mag_stat: readonly number[];
+/**
+ * Create (or find) the object kind for every class book and stamp the
+ * numeric tval/sval back onto the bound ClassBook, exactly as upstream
+ * creates book kinds at class-parse time. Books shared between classes
+ * (e.g. the priest and paladin prayer books) resolve to one kind. Run once
+ * per bound registry, BEFORE building the allocation tables, so books
+ * generate in the dungeon with their book-properties commonness.
+ */
+export declare function registerBookKinds(reg: ObjRegistry, classes: readonly PlayerClass[]): void;
+/** player_spells_init: size the spell flag/order arrays for the class. */
+export declare function playerSpellsInit(player: Player): void;
+/** class_magic_realms: the distinct realms the class casts from. */
+export declare function classMagicRealms(cls: PlayerClass): MagicRealm[];
+/** player_object_to_book: the class book an object is, or null. */
+export declare function playerObjectToBook(player: Player, obj: GameObject): ClassBook | null;
+/** spell_by_index: the class spell with the given class-wide sidx. */
+export declare function spellByIndex(cls: PlayerClass, index: number): ClassSpell | null;
+/** spell_collect_from_book: the sidx list of a book object's spells. */
+export declare function spellCollectFromBook(player: Player, obj: GameObject): number[];
+/** spell_book_count_spells over a tester. */
+export declare function spellBookCountSpells(player: Player, obj: GameObject, tester: (player: Player, spell: number) => boolean): number;
+/** spell_okay_to_cast. */
+/**
+ * spell_okay_list (player-spell.c L320) is upstream's "does ANY spell in this
+ * list pass `spell_test`" fold over spellOkayToCast / spellOkayToStudy. Its one
+ * caller is spell_menu_new (ui-spell.c:233), which refuses to build the menu
+ * when no listed spell qualifies; the web shell's equivalent is the
+ * `items.every((it) => it.disabled)` check in castSpell / studySpell.
+ */
+export declare function spellOkayToCast(player: Player, spell: number): boolean;
+/** spell_okay_to_study. */
+export declare function spellOkayToStudy(player: Player, spellIndex: number): boolean;
+/** spell_okay_to_browse. */
+export declare function spellOkayToBrowse(player: Player, spellIndex: number): boolean;
+/**
+ * obj_can_browse (obj-util.c L775) over obj_kind_can_browse (L762): a book of
+ * one of this class's own realms. The BROWSE book picker's item_tester
+ * (ui-spell.c L340).
+ */
+export declare function objCanBrowse(player: Player, obj: GameObject): boolean;
+/**
+ * obj_can_cast_from (obj-util.c L780): browsable AND holding at least one
+ * spell that passes spell_okay_to_cast. This - not obj_can_browse - is
+ * do_cmd_cast's book item_tester (cmd-obj.c L1129), so a book of the right
+ * realm whose spells are all still unlearned is NEVER offered, and the
+ * remaining books keep the letters they would have in the C.
+ */
+export declare function objCanCastFrom(player: Player, obj: GameObject): boolean;
+/**
+ * obj_can_study (obj-util.c L786): browsable AND holding at least one spell
+ * that passes spell_okay_to_study. do_cmd_study_spell's / do_cmd_study_book's
+ * book item_tester (cmd-obj.c L1187 / L1215) and the filter
+ * player_book_has_unlearned_spells scans with (player-util.c L1330).
+ */
+export declare function objCanStudy(player: Player, obj: GameObject): boolean;
+/** average_spell_stat: the mean casting-stat index over the class realms. */
+export declare function averageSpellStat(cls: PlayerClass, statInd: readonly number[]): number;
+/** Hooks for unported inputs to spell_chance; all optional. */
+export interface SpellChanceEnv {
+    /** player_has(PF_ZERO_FAIL / PF_UNLIGHT / PF_BEAM): class pflags. */
+    hasPf?: (pf: number) => boolean;
+    /** square_islit(cave, player->grid) for the UNLIGHT penalty. */
+    gridIsLit?: () => boolean;
+    /**
+     * player_of_has(p, OF_AFRAID) (player-spell.c:424): fear from ANY source -
+     * the timed TMD_AFRAID synonym OR an OF_AFRAID object/intrinsic flag. The
+     * game caller passes the computed player_state flags here; when omitted the
+     * fallback reads timed[TMD_AFRAID] only, which misses equipment-borne fear.
+     */
+    afraid?: () => boolean;
+}
+/**
+ * spell_chance: the percentage failure chance for a spell, from base fail,
+ * level and casting-stat adjustments, low mana, fear, stunning and amnesia.
+ */
+export declare function spellChance(player: Player, statInd: readonly number[], spellIndex: number, env?: SpellChanceEnv): number;
+/** spell_learn: learn a spell and append it to the learn order. */
+export declare function spellLearn(player: Player, spellIndex: number, msg?: (text: string) => void): void;
+/**
+ * calc_spells (player-calcs.c L1268): how many spells the player may learn,
+ * forgetting or remembering spells as the allowance and level change.
+ * Updates player.upkeep.newSpells.
+ */
+export declare function calcSpells(player: Player, statInd: readonly number[], msg?: (text: string) => void): void;
+/**
+ * state->cumber_armor on its own (player-calcs.c:1524-1529): is the worn armour
+ * heavy enough over the class allowance to cost this player mana? Split out of
+ * calcMana so a caller that must NOT disturb msp/csp - loading a save, where
+ * maximum mana is restored rather than recomputed - can still derive the flag
+ * the encumbrance messages diff against.
+ */
+export declare function cumberArmorFrom(player: Player, armorWeight: number): boolean;
+/**
+ * calc_mana (player-calcs.c L1480): maximum mana from effective levels and
+ * the casting stat, penalized by heavy armor over the class allowance.
+ * `armorWeight` is the summed weight of worn body armor (the caller sums
+ * the non-weapon/bow/ring/amulet/light slots). Updates msp and clamps csp.
+ *
+ * Returns state->cumber_armor (L1503, L1528) - true when the worn armour is
+ * heavy enough to cost mana. Upstream stores it on player_state; the port's
+ * PlayerState carries the same field but calcBonuses cannot fill it (the mana
+ * calc runs in the session layer afterwards), so it is returned here for the
+ * caller to record. It had been left permanently false, which is why the
+ * armour-encumbrance messages could never fire even once they existed.
+ */
+export declare function calcMana(player: Player, statInd: readonly number[], armorWeight: number): boolean;
+/**
+ * player_restore_mana (player.c:351) - DEAD IN 4.2.6.
+ *
+ * Nothing calls it anywhere in the reference tree. The mana-restoring effects
+ * all take the RESTORE_MANA path in effect-handler-general.c, which does its
+ * own arithmetic and prints its own message; this function's
+ * "You feel some of your energies returning." never reaches an upstream
+ * player. Returns whether csp actually moved, as the C does.
+ *
+ * @param msg upstream's unconditional msg(); optional here so a caller can
+ *   route it, since core has no ambient message sink at this layer.
+ */
+export declare function playerRestoreMana(player: Player, amt: number, msg?: (text: string) => void): boolean;
+//# sourceMappingURL=spell.d.ts.map

package/dist/player/spell.d.ts.map

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

package/dist/player/spell.js

@@ -0,0 +1,519 @@
+/**
+ * Player spells, ported from reference/src/player-spell.c (Angband 4.2.6)
+ * plus the spell-related pieces of player-calcs.c (calc_mana, calc_spells,
+ * average_spell_stat) and init.c's write_book_kind (spellbook object kinds
+ * are created FROM the class book definitions, exactly as upstream does at
+ * class-parse time - object.txt carries no book kinds).
+ *
+ * This module is pure player/object domain logic: learning, fail chances,
+ * mana, book lookups. The cast itself (running a spell's effect chain
+ * against the live GameState) lives in game/spell-cmd.ts, the same split as
+ * monster spells (mon/spell.ts vs game/mon-cast.ts).
+ */
+import { TMD, PF, TVAL_ENTRIES } from "../generated/index.js";
+import { newElemInfo, newModifiersRv, newOfFlags } from "../obj/types.js";
+import { adj_mag_mana, adj_mag_study } from "./calcs.js";
+/* ------------------------------------------------------------------ *
+ * Constants and tables.
+ * ------------------------------------------------------------------ */
+/** PY_SPELL_ flags (player.h). */
+export const PY_SPELL = { LEARNED: 0x01, WORKED: 0x02, FORGOTTEN: 0x04 };
+/** Stat Table (INT/WIS) -- minimum spell failure rate (player-spell.c L49). */
+export const adj_mag_fail = [
+    99, 99, 99, 99, 99, 50, 30, 20, 15, 12, 11, 10, 9, 8, 7, 6, 6, 5, 5, 5, 4, 4,
+    4, 4, 3, 3, 2, 2, 2, 2, 1, 1, 1, 1, 1, 0, 0, 0,
+];
+/** Stat Table (INT/WIS) -- failure rate adjustment (player-spell.c L94). */
+export const adj_mag_stat = [
+    -5, -4, -3, -3, -2, -1, 0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
+    15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 45, 48, 51, 54, 57,
+];
+const at = (table, i) => table[Math.max(0, Math.min(i, table.length - 1))] ?? 0;
+function tvalByTextName(name) {
+    const idx = TVAL_ENTRIES.findIndex((t) => t.textName === name);
+    if (idx < 0)
+        throw new Error(`spell: unknown book tval "${name}"`);
+    return idx;
+}
+/**
+ * Create (or find) the object kind for every class book and stamp the
+ * numeric tval/sval back onto the bound ClassBook, exactly as upstream
+ * creates book kinds at class-parse time. Books shared between classes
+ * (e.g. the priest and paladin prayer books) resolve to one kind. Run once
+ * per bound registry, BEFORE building the allocation tables, so books
+ * generate in the dungeon with their book-properties commonness.
+ */
+export function registerBookKinds(reg, classes) {
+    for (const cls of classes) {
+        for (const book of cls.magic.books) {
+            const tval = tvalByTextName(book.tval);
+            /* Check we haven't already made this book. */
+            const existing = reg.kinds.find((k) => k.tval === tval && k.name === book.name);
+            if (existing) {
+                book.tvalIdx = tval;
+                book.sval = existing.sval;
+                continue;
+            }
+            /* The next sval for this tval. */
+            let sval = 0;
+            for (const k of reg.kinds) {
+                if (k.tval === tval && k.sval > sval)
+                    sval = k.sval;
+            }
+            sval += 1;
+            const base = reg.bases[tval];
+            if (!base)
+                throw new Error(`spell: no object base for tval ${tval}`);
+            const graphics = book.graphics;
+            const props = book.properties;
+            let allocMin = 0;
+            let allocMax = 0;
+            if (props?.minmax) {
+                const m = /^(\d+)\s+to\s+(\d+)$/.exec(props.minmax);
+                if (m) {
+                    allocMin = parseInt(m[1], 10);
+                    allocMax = parseInt(m[2], 10);
+                }
+            }
+            const kind = {
+                name: book.name,
+                text: "",
+                base,
+                kidx: reg.kinds.length,
+                tval,
+                sval,
+                pval: { base: 0, dice: 0, sides: 0, mBonus: 0 },
+                toH: { base: 0, dice: 0, sides: 0, mBonus: 0 },
+                toD: { base: 0, dice: 0, sides: 0, mBonus: 0 },
+                toA: { base: 0, dice: 0, sides: 0, mBonus: 0 },
+                ac: 0,
+                dd: 1,
+                ds: 1,
+                weight: 30,
+                cost: props?.cost ?? 0,
+                flags: newOfFlags(),
+                kindFlags: base.kindFlags.clone(),
+                modifiers: newModifiersRv(),
+                elInfo: newElemInfo(),
+                brands: null,
+                slays: null,
+                curses: null,
+                dAttr: graphics?.color ?? "R",
+                dChar: graphics?.glyph ?? "*",
+                allocProb: props?.common ?? 0,
+                allocMin,
+                allocMax,
+                level: allocMin,
+                activation: null,
+                effect: null,
+                power: 0,
+                effectMsg: "",
+                visMsg: "",
+                time: { base: 0, dice: 0, sides: 0, mBonus: 0 },
+                charge: { base: 0, dice: 0, sides: 0, mBonus: 0 },
+                genMultProb: 0,
+                stackSize: { base: 1, dice: 0, sides: 0, mBonus: 0 },
+            };
+            /* NOTE ON ORDER (init.c:208-232 write_book_kind): upstream creates book
+             * kinds while parsing class.txt - BEFORE the special-artifact dummies -
+             * and bumps ordinary_kind_max with each one, so upstream's k_info runs
+             * [object.txt kinds][books][INSTA_ART dummies] and "kidx >=
+             * ordinary_kind_max" means exactly "is a dummy". Here the dummies are
+             * appended during bindCore and the books after it, so books sit ABOVE
+             * ordinaryKindCount. Anything that wants "is this a special-artifact
+             * dummy?" must therefore test the INSTA_ART flag, not the index - which
+             * is what flavorInit does when it marks the ordinary kinds aware. */
+            reg.kinds.push(kind);
+            book.tvalIdx = tval;
+            book.sval = sval;
+        }
+    }
+}
+/* ------------------------------------------------------------------ *
+ * player-spell.c proper.
+ * ------------------------------------------------------------------ */
+/** player_spells_init: size the spell flag/order arrays for the class. */
+export function playerSpellsInit(player) {
+    const num = player.cls.magic.totalSpells;
+    if (!num)
+        return;
+    player.spellFlags = new Array(num).fill(0);
+    player.spellOrder = new Array(num).fill(99);
+}
+/** class_magic_realms: the distinct realms the class casts from. */
+export function classMagicRealms(cls) {
+    const realms = [];
+    if (!cls.magic.totalSpells)
+        return realms;
+    for (const book of cls.magic.books) {
+        if (!realms.some((r) => r.name === book.realm.name)) {
+            realms.push(book.realm);
+        }
+    }
+    return realms;
+}
+/** player_object_to_book: the class book an object is, or null. */
+export function playerObjectToBook(player, obj) {
+    for (const book of player.cls.magic.books) {
+        if (obj.tval === book.tvalIdx && obj.sval === book.sval)
+            return book;
+    }
+    return null;
+}
+/** spell_by_index: the class spell with the given class-wide sidx. */
+export function spellByIndex(cls, index) {
+    const magic = cls.magic;
+    if (index < 0 || index >= magic.totalSpells)
+        return null;
+    let book = 0;
+    let count = 0;
+    while (count + (magic.books[book]?.numSpells ?? 0) - 1 < index) {
+        count += magic.books[book].numSpells;
+        book++;
+    }
+    return magic.books[book]?.spells[index - count] ?? null;
+}
+/** spell_collect_from_book: the sidx list of a book object's spells. */
+export function spellCollectFromBook(player, obj) {
+    const book = playerObjectToBook(player, obj);
+    if (!book)
+        return [];
+    return book.spells.map((s) => s.sidx);
+}
+/** spell_book_count_spells over a tester. */
+export function spellBookCountSpells(player, obj, tester) {
+    const book = playerObjectToBook(player, obj);
+    if (!book)
+        return 0;
+    return book.spells.filter((s) => tester(player, s.sidx)).length;
+}
+/** spell_okay_to_cast. */
+/**
+ * spell_okay_list (player-spell.c L320) is upstream's "does ANY spell in this
+ * list pass `spell_test`" fold over spellOkayToCast / spellOkayToStudy. Its one
+ * caller is spell_menu_new (ui-spell.c:233), which refuses to build the menu
+ * when no listed spell qualifies; the web shell's equivalent is the
+ * `items.every((it) => it.disabled)` check in castSpell / studySpell.
+ */
+export function spellOkayToCast(player, spell) {
+    return ((player.spellFlags[spell] ?? 0) & PY_SPELL.LEARNED) !== 0;
+}
+/** spell_okay_to_study. */
+export function spellOkayToStudy(player, spellIndex) {
+    const spell = spellByIndex(player.cls, spellIndex);
+    return (spell !== null &&
+        spell.level <= player.lev &&
+        ((player.spellFlags[spellIndex] ?? 0) & PY_SPELL.LEARNED) === 0);
+}
+/** spell_okay_to_browse. */
+export function spellOkayToBrowse(player, spellIndex) {
+    const spell = spellByIndex(player.cls, spellIndex);
+    return spell !== null && spell.level < 99;
+}
+/**
+ * obj_can_browse (obj-util.c L775) over obj_kind_can_browse (L762): a book of
+ * one of this class's own realms. The BROWSE book picker's item_tester
+ * (ui-spell.c L340).
+ */
+export function objCanBrowse(player, obj) {
+    return playerObjectToBook(player, obj) !== null;
+}
+/**
+ * obj_can_cast_from (obj-util.c L780): browsable AND holding at least one
+ * spell that passes spell_okay_to_cast. This - not obj_can_browse - is
+ * do_cmd_cast's book item_tester (cmd-obj.c L1129), so a book of the right
+ * realm whose spells are all still unlearned is NEVER offered, and the
+ * remaining books keep the letters they would have in the C.
+ */
+export function objCanCastFrom(player, obj) {
+    return (objCanBrowse(player, obj) &&
+        spellBookCountSpells(player, obj, spellOkayToCast) > 0);
+}
+/**
+ * obj_can_study (obj-util.c L786): browsable AND holding at least one spell
+ * that passes spell_okay_to_study. do_cmd_study_spell's / do_cmd_study_book's
+ * book item_tester (cmd-obj.c L1187 / L1215) and the filter
+ * player_book_has_unlearned_spells scans with (player-util.c L1330).
+ */
+export function objCanStudy(player, obj) {
+    return (objCanBrowse(player, obj) &&
+        spellBookCountSpells(player, obj, spellOkayToStudy) > 0);
+}
+/** average_spell_stat: the mean casting-stat index over the class realms. */
+export function averageSpellStat(cls, statInd) {
+    const realms = classMagicRealms(cls);
+    const count = realms.length;
+    if (!count)
+        return 0;
+    let sum = 0;
+    for (const r of realms)
+        sum += statInd[r.stat] ?? 0;
+    return Math.trunc((sum + count - 1) / count);
+}
+/**
+ * spell_chance: the percentage failure chance for a spell, from base fail,
+ * level and casting-stat adjustments, low mana, fear, stunning and amnesia.
+ */
+export function spellChance(player, statInd, spellIndex, env = {}) {
+    if (!player.cls.magic.totalSpells)
+        return 100;
+    const spell = spellByIndex(player.cls, spellIndex);
+    if (!spell)
+        return 100;
+    const hasPf = env.hasPf ?? ((pf) => player.cls.pflags.has(pf));
+    const statIdx = statInd[spell.realm.stat] ?? 0;
+    /* Base rate, adjusted by effective level and the casting stat. */
+    let chance = spell.fail;
+    chance -= 3 * (player.lev - spell.level);
+    chance -= at(adj_mag_stat, statIdx);
+    /* Not enough mana to cast. */
+    if (spell.mana > player.csp)
+        chance += 5 * (spell.mana - player.csp);
+    /* Get the minimum failure rate for the casting stat level. */
+    let minfail = at(adj_mag_fail, statIdx);
+    /* Non zero-fail characters never get better than 5 percent. */
+    if (!hasPf(PF.ZERO_FAIL) && minfail < 5)
+        minfail = 5;
+    /* Necromancers are punished by being on lit squares. */
+    if (hasPf(PF.UNLIGHT) && (env.gridIsLit?.() ?? false))
+        chance += 25;
+    /* Fear makes spells harder (before minfail). Upstream reads player_of_has(
+     * OF_AFRAID); the fallback below covers only the timed synonym, so the game
+     * caller supplies env.afraid from the computed player_state flags. */
+    const afraid = env.afraid ?? (() => (player.timed[TMD.AFRAID] ?? 0) > 0);
+    if (afraid())
+        chance += 20;
+    /* Minimal and maximal failure rate. */
+    if (chance < minfail)
+        chance = minfail;
+    if (chance > 50)
+        chance = 50;
+    /* Stunning makes spells harder (after minfail). */
+    const stun = player.timed[TMD.STUN] ?? 0;
+    if (stun > 50)
+        chance += 25;
+    else if (stun)
+        chance += 15;
+    /* Amnesia makes spells very difficult. */
+    if ((player.timed[TMD.AMNESIA] ?? 0) > 0) {
+        chance = 50 + Math.trunc(chance / 2);
+    }
+    /* Always a 5 percent chance of working. */
+    if (chance > 95)
+        chance = 95;
+    return chance;
+}
+/** spell_learn: learn a spell and append it to the learn order. */
+export function spellLearn(player, spellIndex, msg) {
+    const spell = spellByIndex(player.cls, spellIndex);
+    if (!spell)
+        return;
+    player.spellFlags[spellIndex] = (player.spellFlags[spellIndex] ?? 0) | PY_SPELL.LEARNED;
+    /* Find the next open entry in spell_order[]. */
+    for (let i = 0; i < player.cls.magic.totalSpells; i++) {
+        if (player.spellOrder[i] === 99) {
+            player.spellOrder[i] = spellIndex;
+            break;
+        }
+    }
+    msg?.(`You have learned the ${spell.realm.spellNoun} of ${spell.name}.`);
+    player.upkeep.newSpells--;
+    if (player.upkeep.newSpells > 0) {
+        msg?.(`You can learn ${player.upkeep.newSpells} more ${spell.realm.spellNoun}` +
+            `${player.upkeep.newSpells !== 1 ? "s" : ""}.`);
+    }
+}
+/* ------------------------------------------------------------------ *
+ * calc_spells / calc_mana (player-calcs.c).
+ * ------------------------------------------------------------------ */
+/**
+ * calc_spells (player-calcs.c L1268): how many spells the player may learn,
+ * forgetting or remembering spells as the allowance and level change.
+ * Updates player.upkeep.newSpells.
+ */
+export function calcSpells(player, statInd, msg) {
+    const magic = player.cls.magic;
+    const numTotal = magic.totalSpells;
+    if (!numTotal)
+        return;
+    /* Save the new_spells value (player-calcs.c:1288) for the change check. */
+    const oldSpells = player.upkeep.newSpells;
+    /* Determine the number of spells allowed. */
+    let levels = player.lev - magic.spellFirst + 1;
+    if (levels < 0)
+        levels = 0;
+    const percentSpells = at(adj_mag_study, averageSpellStat(player.cls, statInd));
+    const numAllowed = Math.trunc((percentSpells * levels + 50) / 100);
+    /* Count the number of spells we know. */
+    let numKnown = 0;
+    for (let j = 0; j < numTotal; j++) {
+        if ((player.spellFlags[j] ?? 0) & PY_SPELL.LEARNED)
+            numKnown++;
+    }
+    player.upkeep.newSpells = numAllowed - numKnown;
+    /* Forget spells which are too hard. */
+    for (let i = numTotal - 1; i >= 0; i--) {
+        const j = player.spellOrder[i] ?? 99;
+        if (j >= 99)
+            continue;
+        const spell = spellByIndex(player.cls, j);
+        if (!spell || spell.level <= player.lev)
+            continue;
+        if ((player.spellFlags[j] ?? 0) & PY_SPELL.LEARNED) {
+            player.spellFlags[j] =
+                ((player.spellFlags[j] ?? 0) | PY_SPELL.FORGOTTEN) & ~PY_SPELL.LEARNED;
+            msg?.(`You have forgotten the ${spell.realm.spellNoun} of ${spell.name}.`);
+            player.upkeep.newSpells++;
+        }
+    }
+    /* Forget spells if we know too many spells. */
+    for (let i = numTotal - 1; i >= 0; i--) {
+        if (player.upkeep.newSpells >= 0)
+            break;
+        const j = player.spellOrder[i] ?? 99;
+        if (j >= 99)
+            continue;
+        const spell = spellByIndex(player.cls, j);
+        if (spell && (player.spellFlags[j] ?? 0) & PY_SPELL.LEARNED) {
+            player.spellFlags[j] =
+                ((player.spellFlags[j] ?? 0) | PY_SPELL.FORGOTTEN) & ~PY_SPELL.LEARNED;
+            msg?.(`You have forgotten the ${spell.realm.spellNoun} of ${spell.name}.`);
+            player.upkeep.newSpells++;
+        }
+    }
+    /* Check for spells to remember. */
+    for (let i = 0; i < numTotal; i++) {
+        if (player.upkeep.newSpells <= 0)
+            break;
+        const j = player.spellOrder[i] ?? 99;
+        if (j >= 99)
+            break;
+        const spell = spellByIndex(player.cls, j);
+        if (!spell || spell.level > player.lev)
+            continue;
+        if ((player.spellFlags[j] ?? 0) & PY_SPELL.FORGOTTEN) {
+            player.spellFlags[j] =
+                ((player.spellFlags[j] ?? 0) & ~PY_SPELL.FORGOTTEN) | PY_SPELL.LEARNED;
+            msg?.(`You have remembered the ${spell.realm.spellNoun} of ${spell.name}.`);
+            player.upkeep.newSpells--;
+        }
+    }
+    /* Cannot learn more spells than exist. */
+    let learnable = 0;
+    for (let j = 0; j < numTotal; j++) {
+        const spell = spellByIndex(player.cls, j);
+        if (!spell || spell.level > player.lev || spell.level === 0)
+            continue;
+        if ((player.spellFlags[j] ?? 0) & PY_SPELL.LEARNED)
+            continue;
+        learnable++;
+    }
+    if (player.upkeep.newSpells > learnable) {
+        player.upkeep.newSpells = learnable;
+    }
+    /* Spell count changed: announce the new allowance (player-calcs.c:1433-1466).
+       The realm spell_noun list is pluralised only when >1 new spell. The
+       old!=new guard means load/boot recalcs (newSpells restored from save) stay
+       silent - only a real change (level-up, stat shift) speaks. */
+    if (oldSpells !== player.upkeep.newSpells && player.upkeep.newSpells > 0) {
+        const realms = classMagicRealms(player.cls);
+        const plural = player.upkeep.newSpells > 1;
+        const suffix = plural ? "s" : "";
+        let buf = realms.length > 0 ? `${realms[0].spellNoun}${suffix}` : "spells";
+        for (let i = 1; i < realms.length; i++) {
+            buf += i < realms.length - 1 ? ", " : " or ";
+            buf += `${realms[i].spellNoun}${suffix}`;
+        }
+        msg?.(`You can learn ${player.upkeep.newSpells} more ${buf}.`);
+    }
+}
+/**
+ * state->cumber_armor on its own (player-calcs.c:1524-1529): is the worn armour
+ * heavy enough over the class allowance to cost this player mana? Split out of
+ * calcMana so a caller that must NOT disturb msp/csp - loading a save, where
+ * maximum mana is restored rather than recomputed - can still derive the flag
+ * the encumbrance messages diff against.
+ */
+export function cumberArmorFrom(player, armorWeight) {
+    if (!player.cls.magic.totalSpells)
+        return false;
+    return Math.trunc((armorWeight - player.cls.magic.spellWeight) / 10) > 0;
+}
+/**
+ * calc_mana (player-calcs.c L1480): maximum mana from effective levels and
+ * the casting stat, penalized by heavy armor over the class allowance.
+ * `armorWeight` is the summed weight of worn body armor (the caller sums
+ * the non-weapon/bow/ring/amulet/light slots). Updates msp and clamps csp.
+ *
+ * Returns state->cumber_armor (L1503, L1528) - true when the worn armour is
+ * heavy enough to cost mana. Upstream stores it on player_state; the port's
+ * PlayerState carries the same field but calcBonuses cannot fill it (the mana
+ * calc runs in the session layer afterwards), so it is returned here for the
+ * caller to record. It had been left permanently false, which is why the
+ * armour-encumbrance messages could never fire even once they existed.
+ */
+export function calcMana(player, statInd, armorWeight) {
+    if (!player.cls.magic.totalSpells) {
+        player.msp = 0;
+        player.csp = 0;
+        player.cspFrac = 0;
+        /* A non-caster leaves cumber_armor at its L1503 reset (L1483-1487 returns
+         * before the armour weigh-in). */
+        return false;
+    }
+    /* Extract "effective" player level. */
+    const levels = player.lev - player.cls.magic.spellFirst + 1;
+    let msp = 0;
+    if (levels > 0) {
+        msp = 1;
+        msp += Math.trunc((at(adj_mag_mana, averageSpellStat(player.cls, statInd)) * levels) / 100);
+    }
+    /* Heavy armor penalizes mana (L1524-1532). */
+    const over = Math.trunc((armorWeight - player.cls.magic.spellWeight) / 10);
+    const cumberArmor = cumberArmorFrom(player, armorWeight);
+    if (cumberArmor)
+        msp -= over;
+    if (msp < 0)
+        msp = 0;
+    if (player.msp !== msp) {
+        player.msp = msp;
+        if (player.csp >= msp) {
+            player.csp = msp;
+            player.cspFrac = 0;
+        }
+    }
+    return cumberArmor;
+}
+/* ------------------------------------------------------------------ *
+ * DEAD CODE IN ANGBAND 4.2.6, ported and cordoned.
+ *
+ * Everything below this line has NO CALLER in the reference tree. It is
+ * ported because the port is a translation of 4.2.6, not of the reachable
+ * subset of 4.2.6: a mod, a future upstream release, or a reader comparing the
+ * two trees should find the function where the C has it, behaving as the C
+ * says. Nothing in core may call these - if a caller ever appears upstream,
+ * the call-site census (packages/cli/src/call-census.ts) will report the port
+ * symbol as unused and the pairing can be made then.
+ * ------------------------------------------------------------------ */
+/**
+ * player_restore_mana (player.c:351) - DEAD IN 4.2.6.
+ *
+ * Nothing calls it anywhere in the reference tree. The mana-restoring effects
+ * all take the RESTORE_MANA path in effect-handler-general.c, which does its
+ * own arithmetic and prints its own message; this function's
+ * "You feel some of your energies returning." never reaches an upstream
+ * player. Returns whether csp actually moved, as the C does.
+ *
+ * @param msg upstream's unconditional msg(); optional here so a caller can
+ *   route it, since core has no ambient message sink at this layer.
+ */
+export function playerRestoreMana(player, amt, msg) {
+    const oldCsp = player.csp;
+    player.csp += amt;
+    if (player.csp > player.msp)
+        player.csp = player.msp;
+    /* PR_MANA redraw is the front end's business. */
+    msg?.("You feel some of your energies returning.");
+    return player.csp !== oldCsp;
+}
+//# sourceMappingURL=spell.js.map