@rpgm-tools/neo-angband-core 0.10.0

package/dist/game/player-turn.js

@@ -0,0 +1,739 @@
+/**
+ * The player-action layer: a string-keyed action registry and the
+ * process_player() command pump, ported from reference/src/cmd-core.c
+ * (cmdq_pop / the command dispatch), game-world.c (process_player and
+ * process_player_cleanup: player->energy -= energy_use) and the move/attack
+ * path of cmd-cave.c / player-util.c / player-attack.c (Angband 4.2.6).
+ *
+ * The registry is the moddability seam (decision 13): a command code maps to
+ * an action that mutates the game state and returns the energy it spent
+ * (0 = a free, non-turn-consuming command). Mods add or replace codes without
+ * touching the core. The built-in actions cover walk (move / melee an
+ * adjacent monster), hold/rest (spend a turn in place) and the stair commands
+ * (signal a level change). Every other command code is registered as a stub
+ * that spends no energy and is ledgered as deferred.
+ *
+ * process_player() reads queued commands through the injected provider
+ * (state.nextCommand) so the loop never blocks on real input, and drains free
+ * commands until one uses energy or the queue empties, exactly as the
+ * upstream do-while around cmdq_pop.
+ */
+import { FEAT, MON_MSG, MON_TMD, MSG, OF, PF, STAT, TF, TMD, TRF } from "../generated/index.js";
+import { DDGRID, DDGRID_DDD, locSum } from "../loc.js";
+import { pyAttack } from "../combat/melee.js";
+import { learnBrandSlayFromMelee } from "../combat/brand-slay.js";
+import { getLore } from "../mon/lore.js";
+import { MDESC, monsterDesc } from "../mon/desc.js";
+import { monsterIsCamouflaged, monsterIsObvious, monsterIsVisible, } from "../mon/predicate.js";
+import { monsterWake } from "../mon/take-hit.js";
+import { MON_TMD_FLG_NOTIFY, monIncTimed } from "../mon/timed.js";
+import { equipLearnFlag, equipLearnOnMeleeAttack } from "../obj/knowledge.js";
+import { playerClearTimed, playerTimedGradeEq } from "../player/timed.js";
+import { arenaInterceptDeath, deleteMonster, movePlayer, squareMonster } from "./context.js";
+import { gearGet } from "./gear.js";
+import { floorPile } from "./floor.js";
+import { isTrappedChest } from "../obj/chest.js";
+import { knownIsClosedDoor, knownIsEnterable, knownIsRubble, knownObject, squareForget, squareIsKnown, squareMemorize, } from "./known.js";
+import { squareIsSeen } from "../world/view.js";
+import { playerConfuseDir } from "./obj-cmd.js";
+import { disturb } from "./player-path.js";
+import { playerAdjustManaPrecise } from "./loop.js";
+import { formatMonsterMessage } from "./mon-message.js";
+import { squareIsWebbed, squareRemoveAllTraps, squareTrap } from "./trap.js";
+import { PY_EXERT, playerCheckTerrainDamage, playerOverExert } from "./world.js";
+/**
+ * The action registry (moddable command table). Built-ins can be replaced and
+ * new codes added; unknown codes fall back to a no-energy stub.
+ */
+export class ActionRegistry {
+    actions = new Map();
+    /** Register (or replace) the action for a command code. */
+    register(code, action) {
+        this.actions.set(code, action);
+    }
+    has(code) {
+        return this.actions.has(code);
+    }
+    /** The action for a code, or undefined if none is registered. */
+    get(code) {
+        return this.actions.get(code);
+    }
+    codes() {
+        return Array.from(this.actions.keys());
+    }
+}
+/** Install the melee side-effect dependencies on the state (session wiring). */
+export function installMeleeSideEffects(state, deps) {
+    state.meleeSideDeps = deps;
+}
+/** player_has over the computed player state, else race/class pflags. */
+function playerHasPf(state, pf) {
+    const ps = state.playerState;
+    if (ps)
+        return ps.pflags.has(pf);
+    const p = state.actor.player;
+    return p.race.pflags.has(pf) || p.cls.pflags.has(pf);
+}
+/** player_of_has over the computed player state flags (equip + innate). */
+function playerOfHasFlag(state, of) {
+    return state.playerState?.flags.has(of) ?? false;
+}
+/**
+ * Build the py_attack side-effect hooks (player-attack.c:669-1012) for an
+ * attack on `mon` at its current grid: the confusion brand, vampiric drain,
+ * bloodlust over-exertion, impact quake, shapechange verbs, shield bash and
+ * COMBAT_REGEN reward, each reading the live GameState. Wiring-dependent
+ * pieces (earthquake / heal effects, temporary brands) come from the
+ * installed MeleeSideDeps.
+ */
+export function buildMeleeHooks(state, mon) {
+    const p = state.actor.player;
+    const deps = state.meleeSideDeps ?? {};
+    const grid = mon.grid;
+    const hooks = {
+        takeHit: {
+            ...(state.becomeAware ? { becomeAware: state.becomeAware } : {}),
+        },
+        /* Confusion attack (blow_side_effects, player-attack.c:672-677). */
+        attConf: (p.timed[TMD.ATT_CONF] ?? 0) > 0,
+        clearAttConf: () => {
+            /* player_clear_timed(p, TMD_ATT_CONF, true, false): route through the
+             * grade machinery for the on-end message when the world env is wired. */
+            const eff = state.world?.timedTable?.[TMD.ATT_CONF];
+            if (eff) {
+                playerClearTimed(p, eff, true, false, state.world?.timedHooks ?? {});
+            }
+            else {
+                p.timed[TMD.ATT_CONF] = 0;
+            }
+        },
+        confuseMonster: (m, dur) => {
+            monIncTimed(state.rng, m, MON_TMD.CONF, dur, MON_TMD_FLG_NOTIFY);
+        },
+        /* Vampiric drain (player-attack.c:877-881). */
+        attVamp: (p.timed[TMD.ATT_VAMP] ?? 0) > 0,
+        healPlayer: (amount) => {
+            if (deps.healHp) {
+                deps.healHp(amount);
+                return;
+            }
+            /* EF_HEAL_HP fallback: constant amount, no RNG. */
+            if (p.chp >= p.mhp || amount <= 0)
+                return;
+            p.chp += amount;
+            if (p.chp >= p.mhp) {
+                p.chp = p.mhp;
+                p.chpFrac = 0;
+            }
+            if (amount < 5)
+                state.msg?.("You feel a little better.");
+            else if (amount < 15)
+                state.msg?.("You feel better.");
+            else if (amount < 35)
+                state.msg?.("You feel much better.");
+            else
+                state.msg?.("You feel very good.");
+        },
+        /* Bloodlust over-exertion (player-attack.c:770-774, 871-874). */
+        bloodlust: (p.timed[TMD.BLOODLUST] ?? 0) > 0,
+        overExertScramble: () => {
+            state.msg?.("You feel strange...");
+            playerOverExert(state, PY_EXERT.SCRAMBLE, 20, 20);
+        },
+        overExertCon: () => {
+            state.msg?.("You feel something give way!");
+            playerOverExert(state, PY_EXERT.CON, 20, 0);
+        },
+        /* Impact earthquakes (player-attack.c:816-819, blow_after_effects). */
+        impact: playerOfHasFlag(state, OF.IMPACT),
+        learnImpact: () => {
+            equipLearnFlag(p, state.runeEnv, OF.IMPACT);
+        },
+        ...(deps.earthquake
+            ? {
+                earthquake: deps.earthquake,
+                monsterGone: () => squareMonster(state, grid) !== mon,
+            }
+            : {}),
+        ...(deps.temp ? { temp: deps.temp } : {}),
+    };
+    /* Shapechange blow substitution (player-attack.c:831-838). */
+    if (p.shape && p.shape.name !== "normal" && p.shape.blows.length > 0) {
+        hooks.shapeBlows = p.shape.blows;
+    }
+    /* Reward BGs with 5% of max SPs, min 1/2 point (player-attack.c:1002). */
+    if (playerHasPf(state, PF.COMBAT_REGEN)) {
+        hooks.combatRegen = () => {
+            const spGain = Math.trunc((Math.max(p.msp, 10) * 16384) / 5);
+            playerAdjustManaPrecise(p, spGain);
+        };
+    }
+    /* Shield bash (player-attack.c:897-978, attempt_shield_bash). */
+    if (playerHasPf(state, PF.SHIELD_BASH)) {
+        const armSlot = p.body.slots.findIndex((s) => s.type === "SHIELD");
+        const shield = armSlot >= 0 ? gearGet(state.gear, p.equipment[armSlot] ?? 0) : null;
+        hooks.shieldBash = {
+            shield,
+            dexInd: state.statInd?.[STAT.DEX] ?? 0,
+            strInd: state.statInd?.[STAT.STR] ?? 0,
+            playerWt: p.wt,
+            totalWeight: p.upkeep.totalWeight,
+            showDamage: state.options?.get("show_damage") ?? false,
+            msg: (text) => state.msg?.(text),
+            stunMonster: (m, dur) => {
+                monIncTimed(state.rng, m, MON_TMD.STUN, dur, 0);
+            },
+            confuseMonster: (m, dur) => {
+                monIncTimed(state.rng, m, MON_TMD.CONF, dur, 0);
+            },
+        };
+    }
+    return hooks;
+}
+/**
+ * The shared player-melee path: learn-on-attack wrapping, py_attack with the
+ * full side-effect hooks, the delayed "flees in terror" message, and kill
+ * handling. Returns the energy used (py_attack's energy_use). Used by the walk
+ * command and the bloodlust random attack.
+ */
+export function attackMonster(state, target) {
+    /* Learning from the attack (player-attack.c L822 equip_learn_on_melee_
+     * attack; obj-slays.c learn_brand_slay_from_melee). */
+    const deps = state.meleeSideDeps ?? {};
+    const monVisible = monsterIsVisible(target);
+    /* health_track (player-attack.c:745-749): hitting something visible makes it
+     * the tracked monster, which is what puts it on the sidebar's health bar. This
+     * was absent, and melee is the commonest way a player acquires a tracked
+     * monster - so the bar stayed blank unless you explicitly targeted. Upstream
+     * does it per blow inside py_attack_real; the assignment is idempotent, so
+     * once before the blow loop is behaviourally identical. */
+    if (monVisible)
+        state.healthWho = target;
+    learnBrandSlayFromMelee(state.actor.player, state.runeEnv, state.actor.weapon, {
+        race: target.race,
+        visible: monVisible,
+        lore: getLore(state.lore, target.race),
+    }, deps.temp);
+    const result = pyAttack(state.rng, state.actor.player, state.actor.combat, state.actor.weapon, target, state.brands, state.slays, {
+        /* chance_of_melee_hit halves unseen targets (player-attack.c:104-109),
+         * and py_attack's delayed fear message uses the same visibility. */
+        monVisible,
+        /* player_of_has(p, OF_AFRAID): py_attack_real refuses the blow and prints
+         * "You are too afraid to attack X!" (player-attack.c L752). For obvious
+         * monsters do_cmd_walk_test short-circuits before this; the check here
+         * covers the invisible-monster walk and open/close/tunnel/alter-into-a-
+         * monster (attackBlocker), which upstream routes straight to py_attack. */
+        afraid: playerOfHasFlag(state, OF.AFRAID),
+        percentDamage: state.options?.get("birth_percent_damage") ?? false,
+        /* avail_energy = MIN(p->energy, move_energy); process_player only runs
+         * with energy >= move_energy, so the full-turn default is upstream's
+         * value at every real call site. */
+        moveEnergy: state.z.moveEnergy,
+        hooks: buildMeleeHooks(state, target),
+    });
+    equipLearnOnMeleeAttack(state.actor.player, state.runeEnv);
+    /* py_attack message slice: hand the blow-by-blow result to the shell for
+     * faithful "You hit/miss/slay the X" text (combat returns HitType keys
+     * only). Before deletion so the monster name is still resolvable. */
+    state.onMelee?.(target, result);
+    /* Hack - delay fear messages (player-attack.c:1023). */
+    if (result.monsterFled) {
+        const flee = formatMonsterMessage(target, MON_MSG.FLEE_IN_TERROR);
+        if (flee)
+            state.msg?.(flee);
+    }
+    if (result.monsterDied && !arenaInterceptDeath(state, target)) {
+        state.onPlayerKill?.(target);
+        deleteMonster(state, target.midx);
+    }
+    return result.energyUsed;
+}
+/**
+ * energy_per_move (player-util.c:323-328): the energy one step costs, taking
+ * extra moves (state->num_moves, OBJ_MOD_MOVES) into account.
+ */
+export function energyPerMove(state) {
+    const num = state.playerState?.numMoves ?? 0;
+    const energy = state.z.moveEnergy;
+    return Math.trunc((energy * (1 + Math.abs(num) - num)) / (1 + Math.abs(num)));
+}
+/**
+ * player_attack_random_monster (player-util.c:794-813): melee a random
+ * adjacent monster ("You angrily lash out at a nearby foe!"). Draws the
+ * starting direction BEFORE the confusion check, as upstream declares
+ * `dir = randint0(8)` in the initializer. Returns the energy used, or -1 when
+ * no monster was attacked (the command proceeds normally).
+ */
+export function playerAttackRandomMonster(state) {
+    const p = state.actor.player;
+    let dir = state.rng.randint0(8);
+    /* Confused players get a free pass. */
+    if ((p.timed[TMD.CONFUSED] ?? 0) > 0)
+        return -1;
+    /* Look for a monster, attack. */
+    for (let i = 0; i < 8; i++, dir++) {
+        const grid = locSum(state.actor.grid, DDGRID_DDD[dir % 8]);
+        const mon = squareMonster(state, grid);
+        if (mon && !monsterIsCamouflaged(mon)) {
+            /* Upstream sets energy_use = move_energy here, but py_attack resets it
+             * to zero and re-accumulates per blow (an upstream quirk preserved:
+             * the assignment is dead). */
+            state.msg?.("You angrily lash out at a nearby foe!");
+            return attackMonster(state, mon);
+        }
+    }
+    return -1;
+}
+/**
+ * walk: melee an adjacent monster (py_attack) or step onto a passable grid,
+ * refreshing FOV via the injected hook. Returns move_energy when the turn is
+ * spent, 0 when blocked by a wall (a bump uses no energy).
+ */
+/**
+ * move_player's pre-step damaging-terrain check (cmd-cave.c L1156-1180), factored
+ * out for the web shell to run BEFORE it queues a walk so it can block on the
+ * yes/no confirm (the core walk action is synchronous and cannot await UI).
+ *
+ * Returns the feature's walk_msg when a deliberate (non-running) step onto fiery
+ * terrain (lava) would cost more than a third of current HP, so the shell prompts
+ * "Really step in?" and, on "no", cancels the move without spending a turn; null
+ * otherwise. Faithful conditions: only when the target grid is actually stepped
+ * onto (not a wall bump, not a monster attack) and the player is not confused
+ * (a confused player is never prompted). Like C, playerCheckTerrainDamage(false)
+ * is drawn whenever an unconfused player steps onto fiery terrain - prompt or not
+ * - which, with the post-turn damage draw, reproduces C's double draw; it learns
+ * no rune. The running-into-lava run_msg branch is a documented follow-up.
+ */
+export function walkTerrainPrompt(state, rawDir) {
+    if (rawDir < 1 || rawDir > 9 || rawDir === 5)
+        return null;
+    /* move_player only checks damaging terrain when not confused (cmd-cave.c
+     * L1157); a confused player is never prompted and draws no terrain-check RNG
+     * here (the randomised direction and any damage happen later in walkAction). */
+    if ((state.actor.player.timed[TMD.CONFUSED] ?? 0) > 0)
+        return null;
+    const offset = DDGRID[rawDir];
+    const next = {
+        x: state.actor.grid.x + offset.x,
+        y: state.actor.grid.y + offset.y,
+    };
+    if (!state.chunk.inBounds(next))
+        return null;
+    /* The confirm is on move_player's actual-step branch, after the monster-attack
+     * and wall branches: no prompt when attacking a monster or bumping a wall. */
+    if (squareMonster(state, next))
+        return null;
+    if (!state.chunk.isPassable(next))
+        return null;
+    if (!state.chunk.isFiery(next))
+        return null;
+    const dam = playerCheckTerrainDamage(state, next, false);
+    /* Non-running walk: prompt only when the step costs more than a third of the
+     * player's current HP (cmd-cave.c L1174-1177). */
+    if (dam > Math.trunc(state.actor.player.chp / 3)) {
+        return state.chunk.feature(next).walkMsg;
+    }
+    return null;
+}
+export function walkAction(state, cmd) {
+    const rawDir = cmd.dir;
+    if (rawDir === undefined || rawDir < 1 || rawDir > 9 || rawDir === 5)
+        return 0;
+    /*
+     * The port merges do_cmd_walk and move_player into one action; upstream's
+     * run_step (player-path.c:2042) calls move_player DIRECTLY, skipping
+     * do_cmd_walk's preamble. `fromRun` says which caller this is, and the one
+     * place it currently changes behaviour is the known-blocked-grid wording
+     * below. The other two preamble steps are unreachable from a run either way:
+     * runAction refuses to start while confused (so player_confuse_dir cannot
+     * redirect a run step) and clears the web underfoot before the first step (and
+     * run_test treats a web ahead as a wall).
+     */
+    const fromRun = cmd.args?.["fromRun"] === true;
+    /*
+     * do_cmd_walk / do_cmd_jump (cmd-cave.c:1288-1297 / 1328-1337): standing in
+     * a web clears the web and spends the turn in place - no movement.
+     */
+    if (!fromRun && squareIsWebbed(state, state.actor.grid)) {
+        state.msg?.("You clear the web.");
+        /* square_remove_all_traps_of_type(web->tidx) (cmd-cave.c:1294). */
+        const web = squareTrap(state, state.actor.grid).find((t) => t.kind.flags.has(TRF.WEB) || t.kind.desc === "web");
+        squareRemoveAllTraps(state, state.actor.grid, web?.tidx ?? -1);
+        return state.z.moveEnergy;
+    }
+    /* do_cmd_walk (cmd-cave.c L1299-1302): confusion randomises the direction.
+     * When it redirects ("You are confused."), the move spends a full turn even
+     * if it dead-ends against a wall (energy_use is set to move_energy before the
+     * walkability test). The bump-open wrapper (installCaveCommands) applies
+     * confusion up front and sets confusedApplied so the RNG is drawn once; a
+     * direct caller (jump, borg, tests) rolls it here. */
+    let dir = rawDir;
+    let confused = false;
+    if (!cmd.confusedApplied) {
+        dir = playerConfuseDir(state, rawDir);
+        confused = dir !== rawDir;
+    }
+    const offset = DDGRID[dir];
+    const next = { x: state.actor.grid.x + offset.x, y: state.actor.grid.y + offset.y };
+    if (!state.chunk.inBounds(next))
+        return confused ? state.z.moveEnergy : 0;
+    const target = squareMonster(state, next);
+    if (target) {
+        /* move_player (cmd-cave.c L1071): a camouflaged monster in the way
+         * surprises the player instead of being attacked - reveal it and wake it,
+         * matching upstream's become_aware + monster_wake(mon, false, 100). */
+        if (monsterIsCamouflaged(target)) {
+            state.becomeAware?.(target);
+            monsterWake(state.rng, target, false, 100);
+            return state.z.moveEnergy;
+        }
+        /* do_cmd_walk_test (cmd-cave.c L1213-1226): an afraid player refuses to
+         * attack an obvious (visible, non-camouflaged) monster - it prints "You are
+         * too afraid to attack X!", learns OF_AFRAID from equipment, and makes no
+         * move. do_cmd_walk sets energy only AFTER the test passes, so an unconfused
+         * refusal costs nothing; a confused walk already spent its full turn. An
+         * invisible monster is not obvious, so it falls through to py_attack, whose
+         * own afraid branch (player-attack.c L752) fires there instead. */
+        if (monsterIsObvious(target) && playerOfHasFlag(state, OF.AFRAID)) {
+            state.msg?.(`You are too afraid to attack ${monsterDesc(target, MDESC.DEFAULT)}!`, "AFRAID");
+            state.sound?.(MSG.AFRAID);
+            equipLearnFlag(state.actor.player, state.runeEnv, OF.AFRAID);
+            return confused ? state.z.moveEnergy : 0;
+        }
+        /* py_attack: the shared melee path with the full blow side-effect suite.
+         * Energy is py_attack's own energy_use (blow_energy per blow), which may
+         * be less than a full turn, exactly as upstream. */
+        return attackMonster(state, target);
+    }
+    /* Bump into a wall: no step, no energy.
+     * A mod may take the walk over through the walkBlockedByDiggable hook
+     * (mod/hooks.ts) - the QoL mod digs here. autoDigStep returns null having drawn
+     * NO RNG when no mod supplied one, so faithful core still just bumps. */
+    if (!state.chunk.isPassable(next)) {
+        /* `!== null`, not `> 0`: a mod may handle the walk and charge ZERO energy
+         * (mod/hooks.ts), and `> 0` silently threw that case away by treating it as
+         * "no mod supplied one". */
+        const dug = state.autoDigStep?.(state, next) ?? null;
+        if (dug !== null)
+            return dug;
+        /*
+         * Upstream splits this by whether the player already KNOWS the grid, and
+         * the port previously used the known-grid wording for both cases.
+         *
+         * Unknown: do_cmd_walk_test lets the walk proceed (cmd-cave.c:1231-1232),
+         * so move_player runs and takes its own !square_ispassable branch
+         * (:1092-1106) - "You FEEL a wall blocking your way", because the player
+         * cannot see it - and MEMORIZES the grid. That mapping side effect is how
+         * you feel your way along an unlit corridor, and it was missing entirely:
+         * bumping an unseen wall left it unmapped forever and announced the wall as
+         * though it had been in plain sight.
+         *
+         * Known: do_cmd_walk_test messages "in the way!" and refuses the move
+         * (:1240-1253), reconciling player memory with what is really there.
+         *
+         * A closed door is silent in the KNOWN case only - the walk override
+         * (installCaveCommands) opens it (move_player's alter branch, :1079-1083) -
+         * so the base action stays a safe fallback when the override is absent
+         * (borg / unit tests). An UNKNOWN closed door does get its own line.
+         */
+        disturb(state);
+        const rubble = state.chunk.isRubble(next);
+        const door = state.chunk.isClosedDoor(next);
+        if (!squareIsKnown(state, next)) {
+            state.msg?.(rubble
+                ? "You feel a pile of rubble blocking your way."
+                : door
+                    ? "You feel a door blocking your way."
+                    : "You feel a wall blocking your way.", "HITWALL");
+            /* square_memorize + square_light_spot at each of :1096, :1100, :1104. */
+            squareMemorize(state, next);
+        }
+        else if (fromRun) {
+            /*
+             * move_player's OWN known-grid branch (cmd-cave.c:1108-1130), whose
+             * wording differs from do_cmd_walk_test's above: "blocking your way", not
+             * "in the way!". It is reached only when something other than a deliberate
+             * walk drives move_player, because a deliberate walk is refused by
+             * do_cmd_walk_test before move_player runs. In 4.2.6 that leaves exactly
+             * one route - run_step (player-path.c:2042). The whirlwind
+             * (effect-handler-attack.c:1838) is NOT a second route, contrary to the
+             * census note: it tests square_ispassable on every candidate grid and
+             * says "The way is barred." rather than moving into one.
+             *
+             * A closed door reports here too (unlike the walk case, where the walk
+             * override opens it), because run_step passes disarm only for a trap.
+             */
+            state.msg?.(rubble
+                ? "There is a pile of rubble blocking your way."
+                : door
+                    ? "There is a door blocking your way."
+                    : "There is a wall blocking your way.", "HITWALL");
+            /* The same memory reconciliation, per branch (:1112-1129). */
+            if (rubble) {
+                if (!knownIsRubble(state, next))
+                    squareMemorize(state, next);
+            }
+            else if (door) {
+                if (!knownIsClosedDoor(state, next))
+                    squareMemorize(state, next);
+            }
+            else if (knownIsEnterable(state, next)) {
+                squareForget(state, next);
+            }
+        }
+        else if (!door) {
+            state.msg?.(rubble
+                ? "There is a pile of rubble in the way!"
+                : "There is a wall in the way!", "HITWALL");
+            /* The memory reconciliation upstream performs alongside each message: a
+             * remembered floor/rubble/door that turns out to be a wall is forgotten
+             * (:1252-1257), and rubble the player misremembered is re-memorized
+             * (:1243-1246). */
+            if (rubble) {
+                if (!knownIsRubble(state, next))
+                    squareMemorize(state, next);
+            }
+            else if (knownIsEnterable(state, next)) {
+                squareForget(state, next);
+            }
+        }
+        /* A confused redirect into a wall still spends the turn (cmd-cave.c
+         * L1300-1302); a deliberate bump refunds all energy. */
+        return confused ? state.z.moveEnergy : 0;
+    }
+    movePlayer(state, next);
+    if (state.updateFov)
+        state.updateFov(state);
+    search(state); /* player_handle_post_move (player-util.c:1633-1634). */
+    /* Autopickup on the new grid (upstream queues CMD_AUTOPICKUP; its energy
+     * cost is folded into this step, see game/pickup.ts). */
+    const pickupCost = state.autoPickup ? state.autoPickup(state) : 0;
+    /* Trap / terrain consequences of the step (move_player -> hit_trap). */
+    state.onPlayerMoved?.(state, next);
+    /* energy_per_move (cmd-cave.c move_player L1163 via player-util.c:323):
+     * extra-moves items make steps cheaper (gap 2.3). */
+    return energyPerMove(state) + pickupCost;
+}
+/**
+ * jump (do_cmd_jump, cmd-cave.c:1319): "walk into a trap" - identical to
+ * do_cmd_walk except move_player is called with disarm=false (cmd-cave.c:1351),
+ * so a known disarmable trap is stepped onto rather than auto-disarmed. The
+ * cave-cmd walk wrapper only auto-disarms for code "walk"; jump falls through
+ * to the step path.
+ */
+export function jumpAction(state, cmd) {
+    return walkAction(state, cmd);
+}
+/**
+ * search (player-util.c:1680-1715): reveal adjacent secret doors and the
+ * traps on known chests.  The only RNG is place_closed_door's one_in_(4), then
+ * randint1(7) on success, once per discovered door in y/x scan order.
+ */
+export function search(state) {
+    const p = state.actor.player;
+    if ((p.timed[TMD.BLIND] ?? 0) > 0 ||
+        !squareIsSeen(state.chunk, state.actor.grid) ||
+        (p.timed[TMD.CONFUSED] ?? 0) > 0 ||
+        (p.timed[TMD.IMAGE] ?? 0) > 0)
+        return;
+    for (let y = state.actor.grid.y - 1; y <= state.actor.grid.y + 1; y++) {
+        for (let x = state.actor.grid.x - 1; x <= state.actor.grid.x + 1; x++) {
+            const grid = { x, y };
+            if (!state.chunk.inBoundsFully(grid))
+                continue;
+            const flags = state.chunk.feature(grid).flags;
+            if (flags.has(TF.DOOR_ANY) && flags.has(TF.ROCK)) {
+                state.msg?.("You have found a secret door.");
+                state.chunk.setFeat(grid, FEAT.CLOSED);
+                if (state.rng.oneIn(4)) {
+                    state.setDoorLock?.(grid, state.rng.randint1(7));
+                }
+                disturb(state);
+            }
+            /*
+             * The C tests knowledge PER OBJECT (`if (!obj->known || ...) continue;`),
+             * which has no exact analogue here: this port's object memory is per GRID
+             * (KnownObjectMemory holds the remembered pile head's glyph, not a shadow
+             * per object), so the closest check is "is this grid's pile remembered".
+             *
+             * For floor piles the two agree, because square_know_pile shadows the
+             * WHOLE pile at once -- either every object on the grid has a shadow or
+             * none does. They diverge only for an object added to an
+             * already-remembered grid since the last know_pile, e.g. a chest dropped
+             * onto a mapped floor: upstream will not discover its trap until the pile
+             * is known again, this will. Narrow, and recorded as a finding rather than
+             * faked, since a per-object shadow is a larger design change.
+             */
+            if (!knownObject(state, grid))
+                continue;
+            for (const obj of floorPile(state, grid)) {
+                if ((state.isIgnored?.(obj) ?? false) || !isTrappedChest(obj))
+                    continue;
+                if (obj.knownPval !== obj.pval) {
+                    state.msg?.("You have discovered a trap on the chest!");
+                    obj.knownPval = obj.pval;
+                    disturb(state);
+                }
+            }
+        }
+    }
+}
+/** hold / rest: stay put and spend a full turn. */
+export function holdAction(state, _cmd) {
+    search(state);
+    return state.z.moveEnergy;
+}
+/**
+ * sleep (do_cmd_sleep, cmd-cave.c:1675): spend a full turn doing nothing.
+ * process_player injects CMD_SLEEP when the player is paralyzed or Knocked Out
+ * (game-world.c:965-968).
+ */
+export function sleepAction(state, _cmd) {
+    return state.z.moveEnergy;
+}
+/**
+ * descend / ascend: signal a level change (player->upkeep->generate_level).
+ * The actual level generation and depth change are DEFERRED to the world
+ * integration; the loop observes the signal and clears it.
+ */
+export function descendAction(state, _cmd) {
+    state.generateLevel = true;
+    return state.z.moveEnergy;
+}
+export function ascendAction(state, _cmd) {
+    state.generateLevel = true;
+    return state.z.moveEnergy;
+}
+/** A deferred command: consumes no turn (ledgered as not yet ported). */
+export function stubAction(_state, _cmd) {
+    return 0;
+}
+/** Command codes registered as stubs (deferred; see game-loop.yaml).
+ * "pickup"/"autopickup" stubs are replaced by installPickup (game/pickup.ts);
+ * "run" is replaced by installRunning (game/player-path.ts). */
+export const STUBBED_COMMANDS = [
+    "tunnel",
+    "cast",
+    "fire",
+    "throw",
+    "quaff",
+    "read",
+    "eat",
+    "use-staff",
+    "aim-wand",
+    "zap-rod",
+    "activate",
+    "pickup",
+    "drop",
+    "wield",
+    "takeoff",
+    "look",
+    "search",
+    "disarm",
+    "open",
+    "close",
+];
+/** Build the default registry: the ported actions plus the deferred stubs. */
+export function createDefaultRegistry() {
+    const reg = new ActionRegistry();
+    reg.register("walk", walkAction);
+    reg.register("jump", jumpAction);
+    reg.register("hold", holdAction);
+    reg.register("rest", holdAction);
+    reg.register("sleep", sleepAction);
+    reg.register("descend", descendAction);
+    reg.register("ascend", ascendAction);
+    for (const code of STUBBED_COMMANDS)
+        reg.register(code, stubAction);
+    return reg;
+}
+/**
+ * Command codes whose upstream game_cmds entry has can_use_energy = false
+ * (cmd-core.c game_cmds): these skip the pre-command bloodlust coercion roll.
+ * Every other code maps to an energy-capable command and draws the roll.
+ */
+const NON_COERCION_COMMANDS = new Set([
+    "inscribe",
+    "uninscribe",
+    "autoinscribe",
+    "sell",
+    "stash",
+    "buy",
+    "retrieve",
+    "retire",
+    "help",
+    "repeat",
+]);
+/**
+ * process_player: drain queued commands until one spends energy, the queue
+ * empties (needsInput), or the player dies / a level change is requested.
+ * Applies the process_player_cleanup energy accounting for the spending
+ * command (player->energy -= energy_use; total_energy += energy_use).
+ */
+export function processPlayer(state, registry) {
+    let energyUsed = 0;
+    do {
+        if (state.isDead || state.generateLevel)
+            break;
+        /* game-world.c:941-947: after the refresh equivalent and before command
+         * preparation, recover an overfull/corrupt pack using calc_inventory's
+         * sorted inven[] view. */
+        state.overflowPack?.();
+        /* Paralyzed or Knocked Out player gets no turn (game-world.c:965-968):
+         * inject CMD_SLEEP so a full-energy no-op is spent and nextCommand is
+         * never consulted. Ordering matches C: after the detect-ore block (not
+         * yet in the port), before command prep / cmdq_pop. */
+        {
+            const p = state.actor.player;
+            const stunEff = state.world?.timedTable?.[TMD.STUN];
+            const knockedOut = stunEff !== undefined &&
+                playerTimedGradeEq(p, stunEff, "Knocked Out");
+            if ((p.timed[TMD.PARALYZED] ?? 0) > 0 || knockedOut) {
+                if (!state.cmdQueue)
+                    state.cmdQueue = [];
+                state.cmdQueue.push({ code: "sleep" });
+            }
+        }
+        /* Drain the internal queue (cmdq) first - self-continuing commands like
+         * running push their follow-up there - then ask the injected provider. */
+        const cmd = state.cmdQueue && state.cmdQueue.length > 0
+            ? state.cmdQueue.shift()
+            : state.nextCommand();
+        if (!cmd)
+            return { needsInput: true, energyUsed: 0 };
+        /* While TMD_COMMAND runs, the player's commands drive the commanded
+         * monster instead (cmd-core.c L333 swaps the command list). */
+        const commanding = (state.actor.player.timed[TMD.COMMAND] ?? 0) > 0 && state.monCommand;
+        const action = commanding
+            ? state.monCommand
+            : (registry.get(cmd.code) ?? stubAction);
+        /* Occasional attack instead for bloodlust-affected characters
+         * (cmd-core.c:373): before an energy-capable command executes, the
+         * coercion roll is drawn (unconditionally, even at zero bloodlust,
+         * matching upstream's randint0(200) < timed[TMD_BLOODLUST]); on success
+         * the command is dropped and a random adjacent monster is attacked.
+         * skip_cmd_coercion is not modelled (save gap 12.6, WP-10). */
+        if (!commanding && !NON_COERCION_COMMANDS.has(cmd.code)) {
+            if (state.rng.randint0(200) <
+                (state.actor.player.timed[TMD.BLOODLUST] ?? 0)) {
+                const spent = playerAttackRandomMonster(state);
+                if (spent >= 0) {
+                    if (spent > 0) {
+                        state.actor.energy -= spent;
+                        state.actor.totalEnergy += spent;
+                        energyUsed = spent;
+                    }
+                    continue;
+                }
+            }
+        }
+        const use = action(state, cmd);
+        if (use > 0) {
+            state.actor.energy -= use;
+            state.actor.totalEnergy += use;
+            energyUsed = use;
+        }
+    } while (energyUsed === 0 && !state.isDead && !state.generateLevel);
+    return { needsInput: false, energyUsed };
+}
+//# sourceMappingURL=player-turn.js.map