@rpgm-tools/neo-angband-core 0.10.0

package/src/game/project-player.ts

@@ -0,0 +1,236 @@
+/**
+ * The project_p driver, ported from reference/src/project-player.c (Angband
+ * 4.2.6): project_p (L800). The player-side counterpart of project_m.
+ *
+ * It applies a projection's damage to the player: resolve seen/blind, adjust
+ * the damage for resistance / immunity / vulnerability (adjust_dam), scale
+ * self-inflicted damage, apply the player's damage reduction, and deal it with
+ * take_hit - then run the per-type side effects and any extra damage they add.
+ * It implements the onPlayer seam of project() (world/project.ts).
+ *
+ * The damage core is fully portable (adjust_dam, player_apply_damage_reduction
+ * and take_hit are ported). The per-PROJ-type side effects
+ * (project_player_handler_*) are heavily entangled with subsystems not yet
+ * modelled - inven_damage (inventory, #20), EF_DRAIN_STAT (#18), player_exp_lose
+ * (experience) - so they are injected as the onSideEffects hook, the same seam
+ * discipline as the project_m driver's deferred consequences. The killer name
+ * (monster_desc / trap name / "yourself") is resolved by the caller, since it
+ * needs the monster-description and trap systems.
+ */
+
+import { PROJ, TMD } from "../generated/index.js";
+import { locEq } from "../loc.js";
+import type { Loc } from "../loc.js";
+import type { Rng } from "../rng.js";
+import { ELEM_MAX } from "../obj/types.js";
+import {
+  playerApplyDamageReduction,
+  takeHit,
+} from "../player/take-hit.js";
+import type {
+  DamageReduction,
+  TakeHitHooks,
+  TakeHitTarget,
+} from "../player/take-hit.js";
+import { adjustDam } from "../world/projection.js";
+import type { ProjectionInfo } from "../world/projection.js";
+
+/** The player state project_p reads and damages. */
+export interface PlayerProjActor extends TakeHitTarget {
+  /** el_info[type].res_level (3 immune, -1 vulnerable, >0 resist). */
+  resistLevel(type: number): number;
+  /** state.dam_red / state.perc_dam_red. */
+  reduction: DamageReduction;
+  /**
+   * minus_ac(p) (obj-gear.c L376-438): attempt to damage a worn armour piece to
+   * an acid hit, returning whether acid damage should be halved. This is a
+   * callback, not a flag, because it has the armour-damage side effect and must
+   * fire exactly once per acid projection (project-player.c L69), so project_p
+   * calls it only inside adjust_dam's PROJ_ACID branch.
+   */
+  minusAc: () => boolean;
+}
+
+/** The projection source, resolved for the player driver. */
+export interface ProjectPlayerSource {
+  /** origin.what == SRC_PLAYER. */
+  isPlayer: boolean;
+  /** origin.what == SRC_MONSTER. */
+  isMonster: boolean;
+  /** Whether the source monster is visible (false hides the source). */
+  monsterVisible?: boolean;
+  /** The kb_str death cause ("yourself", a monster/trap name, "a bug"). */
+  killer: string;
+  /** origin_get_loc(origin): the projection's start grid (FORCE centre). */
+  grid?: Loc;
+  /** origin.what == SRC_TRAP (FORCE jitters an on-the-trap centre). */
+  isTrap?: boolean;
+}
+
+/** Context passed to the per-type side-effect hook (upstream handler context). */
+export interface ProjectPlayerSideContext {
+  origin: ProjectPlayerSource;
+  /** Distance from the blast centre. */
+  r: number;
+  grid: Loc;
+  /** The adjusted (and self-scaled) damage the handler may key effects off. */
+  dam: number;
+  typ: number;
+  /** Monster spell power (0 for non-monster sources). */
+  power: number;
+  /** Mutable: the handler clears it if the effect was not obvious. */
+  obvious: boolean;
+}
+
+/** The consequences the driver defers to the caller. */
+export interface ProjectPlayerHooks {
+  /** msg(). */
+  message?: (text: string) => void;
+  /** disturb(p). */
+  onDisturb?: () => void;
+  /**
+   * The per-PROJ-type player handler: inven damage, timed effects, stat / exp
+   * drain, etc. Returns extra damage to apply (after damage reduction).
+   */
+  onSideEffects?: (ctx: ProjectPlayerSideContext) => number;
+  /** take_hit consequences (onDeath, combatRegen, ...). */
+  takeHit?: TakeHitHooks;
+  /** OPT(player, show_damage). */
+  showDamage?: boolean;
+  /**
+   * update_smart_learn(mon, player, 0, 0, typ) (project-player.c L852): the
+   * source monster learns the player's resist to this projection type. Injected
+   * (not done in the driver) because it needs the live monster and derived
+   * player state, and the driver is deliberately state-free. The engine
+   * (updateSmartLearn, mon/spell.ts) gates every action - and every RNG draw -
+   * on birth_ai_learn, so with the option off this is a pure no-op.
+   */
+  smartLearn?: (typ: number) => void;
+  /**
+   * equip_learn_element(p, res_type) from adjust_dam(actual=true)
+   * (project-player.c L60-62): being hit by an element teaches the player the
+   * resist rune on worn gear that mitigated it (res_type is the ICE->COLD
+   * remapped type). No RNG. Injected because it needs the live player + runeEnv.
+   */
+  equipLearnElement?: (resType: number) => void;
+}
+
+/** Everything the per-grid player driver needs. */
+export interface ProjectPlayerCtx {
+  rng: Rng;
+  actor: PlayerProjActor;
+  /** The player's grid (square_isplayer check). */
+  playerGrid: Loc;
+  projections: readonly ProjectionInfo[];
+  origin: ProjectPlayerSource;
+  /** Monster spell power, passed to the side-effect handler. */
+  power: number;
+  hooks: ProjectPlayerHooks;
+}
+
+/**
+ * project_p for one grid: affect the player (if they are in `grid`) with
+ * projection `typ` for `dam` damage at distance `dist`. `self` allows the
+ * caster to be hit by their own projection (self damage is scaled down).
+ * Returns whether the effect was obvious. Suitable as the onPlayer hook of
+ * project().
+ */
+export function projectPlayer(
+  pctx: ProjectPlayerCtx,
+  dist: number,
+  grid: Loc,
+  dam: number,
+  typ: number,
+  self: boolean,
+): boolean {
+  const { rng, actor, hooks, origin } = pctx;
+
+  const blind = actor.timed[TMD.BLIND]! > 0;
+  let seen = !blind;
+
+  /* The "decoy has been hit" branch (project-player.c L822) runs before the
+   * player-here check; it is applied at the cast layer (project-cast.ts
+   * castProjection onPlayer wrapper), which has the live GameState and the
+   * decoy grid, since this driver is deliberately state-free. */
+
+  /* No player here. */
+  if (!locEq(grid, pctx.playerGrid)) return false;
+
+  /* Don't affect the projector unless explicitly allowed. */
+  if (origin.isPlayer && !self) return false;
+
+  /* A projection from an unseen monster is not seen. */
+  if (origin.isMonster && origin.monsterVisible === false) seen = false;
+
+  /* "Monster sees what is going on": the source monster learns the player's
+   * resist to this projection type (update_smart_learn, project-player.c L852).
+   * Called here in the faithful position - inside the SRC_MONSTER branch, before
+   * the blind message and adjust_dam - so the engine's birth_ai_learn RNG draws
+   * keep upstream order. The binding to the live monster / player state is
+   * injected (game/project-cast.ts) because this driver is state-free. */
+  if (origin.isMonster) hooks.smartLearn?.(typ);
+
+  /* Let the player know what is going on when they cannot see it. */
+  if (!seen) {
+    const bd = pctx.projections[typ]?.blindDesc ?? "something";
+    hooks.message?.(`You are hit by ${bd}!`);
+  }
+
+  /* Adjust damage for resistance/immunity/vulnerability (ICE uses COLD res). */
+  const resType = typ === PROJ.ICE ? PROJ.COLD : typ;
+  /* adjust_dam(actual=true) (project-player.c L60-62): learn the mitigating
+   * resist rune. Fired before the immune short-circuit, exactly as upstream. */
+  if (resType < ELEM_MAX) hooks.equipLearnElement?.(resType);
+  const resLevel = typ < ELEM_MAX ? actor.resistLevel(resType) : 0;
+  /* minus_ac(p) is consulted only inside adjust_dam's PROJ_ACID branch, after
+   * the immune short-circuit (project-player.c L65-70); calling it here fires
+   * the armour-damage side effect exactly when upstream's does. resLevel 3 is
+   * immune (RESIST_IMMUNE), which returns 0 before minus_ac in the C. */
+  const acidMinusAc =
+    typ === PROJ.ACID && resLevel !== 3 ? actor.minusAc() : false;
+  let d = adjustDam(
+    rng,
+    pctx.projections,
+    typ,
+    dam,
+    "randomise",
+    resLevel,
+    acidMinusAc,
+  );
+
+  if (d) {
+    /* Self-inflicted damage is scaled down. */
+    if (self) d = Math.trunc(d / 10);
+
+    /* Damage reduction affects only the dealt damage, not the side effects. */
+    const reduced = playerApplyDamageReduction(actor, actor.reduction, d);
+    if (reduced > 0 && hooks.showDamage) {
+      hooks.message?.(`You take ${reduced} damage.`);
+    }
+    takeHit(actor, reduced, origin.killer, hooks.takeHit);
+  }
+
+  /* Handle side effects, possibly including extra damage. */
+  const sideCtx: ProjectPlayerSideContext = {
+    origin,
+    r: dist,
+    grid,
+    dam: d,
+    typ,
+    power: pctx.power,
+    obvious: true,
+  };
+  if (!actor.isDead && hooks.onSideEffects) {
+    let xtra = hooks.onSideEffects(sideCtx);
+    xtra = playerApplyDamageReduction(actor, actor.reduction, xtra);
+    if (xtra > 0 && hooks.showDamage) {
+      hooks.message?.(`You take an extra ${xtra} damage.`);
+    }
+    takeHit(actor, xtra, origin.killer, hooks.takeHit);
+  }
+
+  /* Disturb */
+  hooks.onDisturb?.();
+
+  return sideCtx.obvious;
+}

package/src/game/quest.ts

@@ -0,0 +1,248 @@
+/**
+ * The quest system, ported from reference/src/player-quest.c (Angband 4.2.6):
+ * the standard quest table (bound from quest.json), the per-character quest
+ * history, and the on-death bookkeeping that culminates in the game's WIN
+ * CONDITION - slaying Morgoth.
+ *
+ * The base game ships two quests (quest.txt): Sauron on depth 99 and Morgoth
+ * on depth 100, each requiring a single kill. Killing the last incomplete
+ * quest's guardian sets player->total_winner and prints the victory message.
+ *
+ * Provenance and RNG: the whole subsystem is RNG-free EXCEPT build_quest_stairs
+ * (player-quest.c L187), whose scatter loop draws from the game RNG - and even
+ * that fires only when a quest is completed on a grid that cannot hold a
+ * staircase directly, staggering to a neighbouring grid. The common case (a
+ * guardian dying on open floor) consumes no RNG.
+ *
+ * The parser-side pieces of player-quest.c (init/finish_parse_quest,
+ * player_quests_free) have no analogue here: quest.json is already compiled and
+ * the player quest list is a plain array reset at birth, so there is nothing to
+ * free.
+ */
+
+import { FEAT } from "../generated/index.js";
+import type { Loc } from "../loc.js";
+import type { MonsterRegistry } from "../mon/bind.js";
+import type { MonsterRace } from "../mon/types.js";
+import type { Monster } from "../mon/monster.js";
+import type { Player, PlayerQuest } from "../player/player.js";
+import { scatter } from "../world/scatter.js";
+import type { GameState } from "./context.js";
+import { pushObject } from "./project-feat.js";
+import { floorPile } from "./floor.js";
+
+/** One record of quest.json (quest.txt): a guardian, its depth and count. */
+export interface QuestRecordJson {
+  name: string;
+  level: number;
+  /** The guardian monster's name, resolved to a race at bind time. */
+  race: string;
+  /** max_num: kills needed to complete the quest. */
+  number: number;
+}
+
+/**
+ * A bound standard quest (struct quest): the registry template every new
+ * character's quest history is copied from (player_quests_reset).
+ */
+export interface Quest {
+  /** quest->index: position in the quest table (file order). */
+  index: number;
+  name: string;
+  level: number;
+  /** quest->race: the resolved guardian race. */
+  race: MonsterRace;
+  /** quest->max_num. */
+  maxNum: number;
+}
+
+/**
+ * finish_parse_quest (player-quest.c L90): build the direct-access quest table
+ * from the compiled records, resolving each race by name (lookup_monster). The
+ * JSON records are already in file order, so `index` is just the array
+ * position - no linked-list reversal is needed.
+ */
+export function bindQuests(
+  records: readonly QuestRecordJson[],
+  monsters: MonsterRegistry,
+): Quest[] {
+  return records.map((rec, index) => {
+    const race = monsters.raceByName(rec.race);
+    if (!race) {
+      throw new Error(
+        `quest: could not find race '${rec.race}' for quest '${rec.name}'`,
+      );
+    }
+    return { index, name: rec.name, level: rec.level, race, maxNum: rec.number };
+  });
+}
+
+/**
+ * player_quests_reset (player-quest.c L157): copy the standard quest table into
+ * the player's quest history, with every kill count reset to zero. Called at
+ * birth (generatePlayer / startGame).
+ */
+export function playerQuestsReset(p: Player, quests: readonly Quest[]): void {
+  p.quests = quests.map((q) => ({
+    name: q.name,
+    level: q.level,
+    race: q.race.ridx,
+    maxNum: q.maxNum,
+    curNum: 0,
+  }));
+}
+
+/**
+ * is_quest (player-quest.c L140): is `level` a quest level for this player?
+ * Town (level 0) is never a quest; otherwise true when any of the player's
+ * quests is fought on that depth.
+ */
+export function isQuest(p: Player, level: number): boolean {
+  /* Town is never a quest. */
+  if (!level) return false;
+  for (const q of p.quests) {
+    if (q.level === level) return true;
+  }
+  return false;
+}
+
+/**
+ * dungeon_get_next_level (player-util.c L1147): the depth `added` stair-steps
+ * from `dlev`, clamped to the world and STOPPED BY AN OUTSTANDING QUEST.
+ *
+ * Provenance is player-util.c, but it lives here because the quest scan is the
+ * whole point of it: the intermediate-level loop (L1163-1165) returns the first
+ * quest depth at or below `dlev`, so stairs down from 99 with Sauron alive land
+ * on 99 again rather than delivering the player to Morgoth. quest_check clears
+ * a finished quest's level to 0 (quest.ts:185, player-quest.c:232), which is
+ * what re-opens the descent.
+ *
+ * Every C caller of this goes through here (12 sites: the two stair commands,
+ * RECALL, DEEP_DESCENT and its countdown, TELEPORT_LEVEL, and TRF_DOWN traps).
+ * It is deliberately total - no seam, no default - because the previous shape,
+ * an injectable `getNextLevel` that nothing ever wired, silently degraded every
+ * one of those sites to a bare `depth + dir`.
+ */
+export function dungeonGetNextLevel(
+  p: Player,
+  dlev: number,
+  added: number,
+  z: { readonly stairSkip: number; readonly maxDepth: number },
+): number {
+  /* Get target level. */
+  let target = dlev + added * z.stairSkip;
+
+  /* Don't allow levels below max, or above the town. */
+  if (target > z.maxDepth - 1) target = z.maxDepth - 1;
+  if (target < 0) target = 0;
+
+  /* Check intermediate levels for quests. */
+  for (let i = dlev; i <= target; i++) {
+    if (isQuest(p, i)) return i;
+  }
+
+  return target;
+}
+
+/**
+ * square_changeable (cave-square.c L868): a grid that may be "destroyed" - no
+ * permanent walls, shops or stairs, and no artifact lying on it. Reimplemented
+ * locally (the effect-terrain.c copy is module-private) so build_quest_stairs
+ * matches upstream's staircase-placement guard exactly.
+ */
+function squareChangeable(state: GameState, grid: Loc): boolean {
+  const c = state.chunk;
+  if (c.isPerm(grid) || c.isShop(grid) || c.isStairs(grid)) return false;
+  for (const obj of floorPile(state, grid)) {
+    if (obj.artifact) return false;
+  }
+  return true;
+}
+
+/**
+ * build_quest_stairs (player-quest.c L187): create the magical down-staircase
+ * that appears when a quest guardian falls. Staggers away from a grid that
+ * cannot take a staircase (passable, not a door, but not changeable - e.g. a
+ * mineral vein or rubble) to a nearby one, pushes any objects off the chosen
+ * grid, announces the staircase and sets FEAT_MORE.
+ *
+ * The scatter(cave, ..., 1, false) draw is the only RNG in the quest system;
+ * it fires only while the loop guard holds (a rare death location), so a
+ * guardian dying on open floor - which is changeable - consumes no RNG.
+ */
+function buildQuestStairs(state: GameState, grid: Loc): void {
+  const c = state.chunk;
+
+  /* Stagger around until the grid can hold a staircase. */
+  while (
+    !squareChangeable(state, grid) &&
+    c.isPassable(grid) &&
+    !c.isDoor(grid)
+  ) {
+    const newGrid = scatter(c, state.rng, grid, 1, false);
+    /* scatter leaves the output untouched when no grid is feasible; mirror
+     * that by keeping the current grid rather than looping forever. */
+    if (!newGrid) break;
+    grid = newGrid;
+  }
+
+  /* Push any objects. */
+  pushObject(state, grid);
+
+  /* Explain the staircase. */
+  state.msg?.("A magical staircase appears...");
+
+  /* Create stairs down. */
+  c.setFeat(grid, FEAT.MORE);
+
+  /* Update the visuals (PU_UPDATE_VIEW | PU_MONSTERS). */
+  state.updateFov?.(state);
+}
+
+/**
+ * quest_check (player-quest.c L219): the now-dead monster `m` may be a quest
+ * guardian. Increments the matching quest's kill count when the current depth
+ * and race line up; on completion clears the quest (level = 0) and builds the
+ * escape staircase; and when no incomplete quests remain, wins the game.
+ *
+ * Returns whether a quest was completed by this death. The bookkeeping order
+ * (increment -> mark complete -> count remaining -> act) matches upstream
+ * exactly, so the "last quest" detection is identical.
+ */
+export function questCheck(state: GameState, p: Player, m: Monster): boolean {
+  let total = 0;
+  let completed = false;
+
+  /* Mark quests as complete. */
+  for (const q of p.quests) {
+    /* Note completed quests. */
+    if (state.chunk.depth === q.level && m.race.ridx === q.race) {
+      q.curNum++;
+
+      if (q.curNum === q.maxNum) {
+        q.level = 0;
+        completed = true;
+      }
+    }
+
+    /* Count incomplete quests. */
+    if (q.level) total++;
+  }
+
+  if (completed) {
+    /* Build magical stairs. */
+    buildQuestStairs(state, m.grid);
+
+    /* Nothing left, game over... */
+    if (total === 0) {
+      p.totalWinner = true;
+      state.msg?.("*** CONGRATULATIONS ***");
+      state.msg?.("You have won the game!");
+      state.msg?.("You may retire (key is shift-q) when you are ready.");
+    }
+
+    return true;
+  }
+
+  return false;
+}