@rpgm-tools/neo-angband-core 0.10.0

package/src/game/project-cast.ts

@@ -0,0 +1,766 @@
+/**
+ * The projection-casting spine, the game-layer glue that makes the projection
+ * stack usable. It wires the two projection drivers - game/project-monster.ts
+ * (projectMonster) and game/project-player.ts (projectPlayer) - to the generic
+ * beam/bolt/ball/arc driver project() (world/project.ts) using the live
+ * GameState.
+ *
+ * castProjection is the core: it assembles project()'s ProjectHooks from the
+ * two drivers plus GameState (and the injected hooks for the genuinely
+ * downstream consequences those drivers defer - kills/drops/exp, polymorph,
+ * teleport, inventory damage, stat/exp drain, messages) and runs one
+ * projection. This is the single entry point the attack effect handlers (#18),
+ * monster spells (#19) and player spellcasting (#22) all dispatch a projection
+ * through. The flag-shape helpers (castBolt / castBeam / castBall) preset
+ * project()'s flags and radius exactly as the matching effect_handler_* in
+ * effect-handler-attack.c and delegate to it: castBolt / castBeam / castBall /
+ * castArc / castBreath / castShortBeam / castLine / castAlter / castSpot /
+ * castSphere / castStrike / castStar / castStarBall / castTouch / castSwarm /
+ * castProjectLos.
+ *
+ * The target grid is resolved by the caller. resolveAimedTarget ports the
+ * portable branches of get_target (effect-handler-attack.c L38): the player
+ * and no-source cases fully, and the monster case to the player's grid. The
+ * monster confused-direction / target-monster / decoy branches need the
+ * monster-spell targeting and decoys (both #19+), so #19 resolves those and
+ * passes the grid in.
+ *
+ * The player-projection actor (PlayerProjActor: resist levels, damage
+ * reduction, minus_ac) is supplied by the caller, exactly as PlayerActor's
+ * combat / defense views are, because calc_bonuses (which derives them) is
+ * deferred. basicPlayerActor builds the no-resist, no-reduction view over the
+ * live Player for callers and tests until calc_bonuses lands; take_hit's
+ * mutations (chp, is_dead) write back through it to the live player/state.
+ */
+
+import { PF, TMD } from "../generated/index.js";
+import { DIR_TARGET } from "../effects/interpreter.js";
+import { DDGRID, DDGRID_DDD, loc, locEq, locSum } from "../loc.js";
+import type { Loc } from "../loc.js";
+import { monsterIsVisible } from "../mon/predicate.js";
+import { PROJECT, project } from "../world/project.js";
+import type {
+  BoltStep,
+  Projection,
+  ProjectHooks,
+  ProjectParams,
+} from "../world/project.js";
+import { los, squareIsView } from "../world/view.js";
+import type { ProjectionInfo } from "../world/projection.js";
+import type { DamageReduction } from "../player/take-hit.js";
+import { monsterMax } from "./context.js";
+import type { GameState } from "./context.js";
+import { destroyDecoy, monsterGetTarget } from "./effect-mon-origin.js";
+import { projectMonster } from "./project-monster.js";
+import type { ProjectMonsterHooks } from "./project-monster.js";
+import { updateSmartLearn } from "../mon/spell.js";
+import { buildSmartLearnEnv } from "./mon-cast.js";
+import { projectPlayer } from "./project-player.js";
+import { projectObject } from "./project-obj.js";
+import { projectFeature } from "./project-feat.js";
+import { squareIsBelievedWall } from "./known.js";
+import type { PlayerProjActor, ProjectPlayerHooks } from "./project-player.js";
+
+/** option.c: op_ptr->hitpoint_warn default (0..9). Canonical in player/options. */
+import { DEFAULT_HITPOINT_WARN } from "../player/options.js";
+export { DEFAULT_HITPOINT_WARN };
+
+/**
+ * The projection source, unified across the two drivers. Built from a struct
+ * source with playerCastSource / monsterCastSource, or by hand.
+ */
+export interface CastSource {
+  /** origin.what == SRC_PLAYER. */
+  isPlayer: boolean;
+  /** origin.what == SRC_MONSTER. */
+  isMonster: boolean;
+  /** origin.which.monster (midx); 0 when the source is not a monster. */
+  monster: number;
+  /** origin_get_loc(origin): the projection's start grid. */
+  grid: Loc;
+  /** player_has(PF_CHARM): boosts a player projection's effects vs animals. */
+  charm?: boolean;
+  /** monster_is_visible(source): false hides an unseen monster source. */
+  monsterVisible?: boolean;
+  /** kb_str death cause for take_hit ("an orc", "a trap", "yourself"). */
+  killer?: string;
+  /** Monster spell power, forwarded to the player side-effect handler. */
+  power?: number;
+  /** origin.what == SRC_TRAP (FORCE's on-the-trap centre jitter). */
+  isTrap?: boolean;
+}
+
+/** source_player(): a player-origin cast from the live player grid. */
+export function playerCastSource(
+  state: GameState,
+  opts: { charm?: boolean; killer?: string } = {},
+): CastSource {
+  return {
+    isPlayer: true,
+    isMonster: false,
+    monster: 0,
+    grid: state.actor.grid,
+    /* project-mon.c L1346: player_has(PF_CHARM), not a caller default. */
+    charm:
+      opts.charm ??
+      (state.playerState?.pflags.has(PF.CHARM) ??
+        (state.actor.player.race.pflags.has(PF.CHARM) ||
+          state.actor.player.cls.pflags.has(PF.CHARM))),
+    killer: opts.killer ?? "yourself",
+  };
+}
+
+/** source_monster(midx): a monster-origin cast from that monster's grid. */
+export function monsterCastSource(
+  state: GameState,
+  midx: number,
+  opts: { killer?: string; power?: number } = {},
+): CastSource {
+  const mon = state.monsters[midx] ?? null;
+  return {
+    isPlayer: false,
+    isMonster: true,
+    monster: midx,
+    grid: mon ? mon.grid : loc(-1, -1),
+    monsterVisible: mon ? monsterIsVisible(mon) : false,
+    killer: opts.killer ?? "a monster",
+    power: opts.power ?? 0,
+  };
+}
+
+/** The consequences and UI seams a cast defers to its caller. */
+export interface CastHooks {
+  /** project_m's deferred consequences (kills, poly, teleport, messages). */
+  monster?: ProjectMonsterHooks;
+  /** project_p's deferred consequences (side effects, take_hit, messages). */
+  player?: ProjectPlayerHooks;
+  /** UI: one traveled bolt/beam step (suppressed when the player is blind). */
+  onBolt?: (step: BoltStep, typ: number, beam: boolean) => void;
+  /** UI: the whole blast, once, before per-grid effects. */
+  onBlast?: (proj: Projection, typ: number) => void;
+  /** Recall / health-track the single monster a player projection hit. */
+  onTrackMonster?: (grid: Loc) => void;
+}
+
+/** Everything a cast needs beyond the source and the shot parameters. */
+export interface CastContext {
+  /** The bound projection table (world/projection.ts bindProjections). */
+  projections: readonly ProjectionInfo[];
+  /** z_info->max_range. */
+  maxRange: number;
+  /** The player-projection actor (resist / reduction view; see module doc). */
+  playerActor: PlayerProjActor;
+  hooks?: CastHooks;
+  /**
+   * World seams for project_o / project_f (floor destruction, stone-to-mud,
+   * trap and door effects). When absent, PROJECT.ITEM / PROJECT.GRID
+   * projections skip objects and terrain (the pre-#20/#21 behaviour).
+   */
+  worldEnv?: import("./project-feat.js").ProjectFeatEnv;
+}
+
+/**
+ * basicPlayerActor: the no-resist, no-reduction player-projection view over the
+ * live Player, for callers and tests until calc_bonuses (el_info, dam_red,
+ * perc_dam_red, minus_ac) lands. chp and is_dead are live so take_hit's
+ * mutations write back to the player and the game state.
+ */
+export function basicPlayerActor(
+  state: GameState,
+  opts: {
+    /** state.el_info[type].res_level from the live derived state. */
+    resistLevel?: (type: number) => number;
+    /** state.dam_red / perc_dam_red from the live derived state. */
+    reduction?: () => DamageReduction;
+    /** minus_ac(p): damage a worn armour piece to acid, returning the halving
+     * flag (obj-gear.c L376-438). Default no armour effect. */
+    minusAc?: () => boolean;
+  } = {},
+): PlayerProjActor {
+  const p = state.actor.player;
+  return {
+    get chp(): number {
+      return p.chp;
+    },
+    set chp(v: number) {
+      p.chp = v;
+    },
+    get mhp(): number {
+      return p.mhp;
+    },
+    get lev(): number {
+      return p.lev;
+    },
+    get isDead(): boolean {
+      return state.isDead;
+    },
+    set isDead(v: boolean) {
+      state.isDead = v;
+    },
+    timed: p.timed,
+    hitpointWarn: DEFAULT_HITPOINT_WARN,
+    resistLevel: opts.resistLevel ?? ((): number => 0),
+    get reduction(): DamageReduction {
+      return opts.reduction ? opts.reduction() : { damRed: 0, percDamRed: 0 };
+    },
+    minusAc: opts.minusAc ?? ((): boolean => false),
+  };
+}
+
+/**
+ * get_target (effect-handler-attack.c L38) for the aimed bolt/beam family.
+ * Returns the target grid and whether PROJECT_PLAY should be set (get_target
+ * sets it for monster and no-source projections so they can hit the player).
+ *
+ * - SRC_PLAYER: DIR_TARGET with an acquired target aims at it; otherwise the
+ *   adjacent grid in `dir`. The target system (target_okay / target_get) is
+ *   deferred (#24), so the acquired grid is passed in as `aimed`.
+ * - SRC_MONSTER: monsterGetTarget resolves confusion's random direction (one
+ *   randint1(100) draw always made, matching the upstream RNG stream), then a
+ *   targeted monster, the decoy, or the player.
+ * - default (SRC_NONE / trap / object): aims at the player, sets PROJECT_PLAY.
+ */
+export function resolveAimedTarget(
+  state: GameState,
+  source: CastSource,
+  dir: number,
+  aimed?: Loc,
+): { grid: Loc; play: boolean } {
+  if (source.isPlayer) {
+    if (dir === DIR_TARGET && aimed) return { grid: aimed, play: false };
+    return { grid: locSum(state.actor.grid, DDGRID[dir] ?? loc(0, 0)), play: false };
+  }
+  if (source.isMonster) {
+    return { grid: monsterGetTarget(state, state.rng, source.monster), play: true };
+  }
+  /* No-source projections target the player and may hit them. */
+  return { grid: state.actor.grid, play: true };
+}
+
+/**
+ * castProjection: assemble project()'s hooks from the two drivers plus the live
+ * GameState and fire one projection at `target`. `flg` is the fully-resolved
+ * PROJECT_* flag set; `rad` is 0 for a bolt/beam or the ball/arc radius. Returns
+ * project()'s notice value (the player observed some effect). This is the seam
+ * every attack effect, monster spell and player spell dispatches through.
+ */
+export function castProjection(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  flg: number,
+  rad: number,
+  degreesOfArc = 0,
+  diameterOfSource = 0,
+): boolean {
+  const hooks = cctx.hooks ?? {};
+
+  const monCtx = {
+    state,
+    projections: cctx.projections,
+    origin: {
+      isPlayer: source.isPlayer,
+      monster: source.monster,
+      grid: source.grid,
+      charm: source.charm ?? false,
+    },
+    hooks: hooks.monster ?? {},
+  };
+
+  const plCtx = {
+    rng: state.rng,
+    actor: cctx.playerActor,
+    playerGrid: state.actor.grid,
+    projections: cctx.projections,
+    origin: {
+      isPlayer: source.isPlayer,
+      isMonster: source.isMonster,
+      ...(source.monsterVisible !== undefined
+        ? { monsterVisible: source.monsterVisible }
+        : {}),
+      killer: source.killer ?? "a bug",
+      /* origin_get_loc + SRC_TRAP, for the FORCE thrust centre. */
+      grid: source.grid,
+      ...(source.isTrap !== undefined ? { isTrap: source.isTrap } : {}),
+    },
+    power: source.power ?? 0,
+    /* update_smart_learn (mon-util.c L788): a monster-source projection that
+     * hits the player lets the monster learn the player's resist/flag for that
+     * GF type. Merge the per-cast smartLearn hook onto the player hooks for
+     * monster sources only. With birth_ai_learn off, updateSmartLearn returns
+     * before drawing RNG (equipLearn* aside), so default play is unchanged. */
+    hooks: {
+      ...(hooks.player ?? {}),
+      ...(source.isMonster && source.monster > 0
+        ? {
+            smartLearn: (typ: number): void => {
+              const mon = state.monsters[source.monster];
+              if (mon) {
+                updateSmartLearn(state.rng, mon, buildSmartLearnEnv(state), 0, 0, typ);
+              }
+            },
+          }
+        : {}),
+    },
+  };
+
+  const projectHooks: ProjectHooks = {
+    onMonster: (dist, g, d, t, f) => projectMonster(monCtx, dist, g, d, t, f),
+    onPlayer: (dist, g, d, t, self) => {
+      /* project_p (project-player.c L822): a damaging projection that reaches
+       * the player's decoy grid destroys it, whether or not the player is
+       * there. */
+      if (d && state.decoy && locEq(g, state.decoy)) {
+        destroyDecoy(state, cctx.worldEnv?.trapDeps, (text) =>
+          cctx.worldEnv?.msg?.(text),
+        );
+      }
+      return projectPlayer(plCtx, dist, g, d, t, self);
+    },
+    playerIsDead: () => cctx.playerActor.isDead,
+    ...(hooks.onTrackMonster ? { onTrackMonster: hooks.onTrackMonster } : {}),
+    ...(hooks.onBolt ? { onBolt: hooks.onBolt } : {}),
+    ...(hooks.onBlast ? { onBlast: hooks.onBlast } : {}),
+    /* project_o / project_f over the live floor piles and terrain. */
+    ...(cctx.worldEnv
+      ? {
+          onObject: (dist: number, g: Loc, d: number, t: number): boolean =>
+            projectObject(state, dist, g, d, t, cctx.worldEnv),
+          onFeature: (dist: number, g: Loc, d: number, t: number): boolean =>
+            projectFeature(state, dist, g, d, t, cctx.worldEnv),
+        }
+      : {}),
+  };
+
+  const params: ProjectParams = {
+    origin: source.grid,
+    finish: target,
+    rad,
+    typ,
+    flg,
+    dam,
+    maxRange: cctx.maxRange,
+    sourceIsPlayer: source.isPlayer,
+    blind: cctx.playerActor.timed[TMD.BLIND]! > 0,
+    degreesOfArc,
+    diameterOfSource,
+    believedWall: (grid) => squareIsBelievedWall(state, grid),
+  };
+
+  return project(state.chunk, params, projectHooks);
+}
+
+/**
+ * effect_handler_BOLT: a bolt that stops at the first monster. project_aimed
+ * adds PROJECT_THRU; get_target adds PROJECT_PLAY for a non-player source.
+ */
+export function castBolt(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  extraFlg = 0,
+): boolean {
+  let flg = PROJECT.STOP | PROJECT.KILL | PROJECT.THRU;
+  if (!source.isPlayer) flg |= PROJECT.PLAY;
+  /* BOLT_AWARE adds PROJECT_AWARE when the caster is aware of the effect
+     (effect-handler-attack.c:402), so the hit is "obvious" and does not try to
+     ID its source. */
+  flg |= extraFlg;
+  return castProjection(state, cctx, source, target, dam, typ, flg, 0);
+}
+
+/**
+ * effect_handler_BEAM: a beam that passes through monsters. As castBolt but
+ * PROJECT_BEAM instead of PROJECT_STOP.
+ */
+export function castBeam(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+): boolean {
+  let flg = PROJECT.BEAM | PROJECT.KILL | PROJECT.THRU;
+  if (!source.isPlayer) flg |= PROJECT.PLAY;
+  return castProjection(state, cctx, source, target, dam, typ, flg, 0);
+}
+
+/**
+ * effect_handler_BALL: an exploding ball. A monster source adds PROJECT_PLAY
+ * and drops STOP/THRU so it detonates on the player; a player source drops
+ * STOP/THRU only when a specific target was acquired (aimedAtTarget), so a
+ * bare-direction ball still stops at the first obstacle. `rad` defaults to 2
+ * upstream; the caller applies any powerful-monster or player-level radius
+ * bonus before calling.
+ */
+export function castBall(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  rad = 2,
+  opts: { aimedAtTarget?: boolean } = {},
+): boolean {
+  let flg =
+    PROJECT.THRU | PROJECT.STOP | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  if (source.isMonster) {
+    flg |= PROJECT.PLAY;
+    flg &= ~(PROJECT.STOP | PROJECT.THRU);
+  } else if (source.isPlayer && opts.aimedAtTarget) {
+    flg &= ~(PROJECT.STOP | PROJECT.THRU);
+  }
+  return castProjection(state, cctx, source, target, dam, typ, flg, rad);
+}
+
+/**
+ * effect_handler_LINE (L173): a beam that also affects grids (e.g. light).
+ * As castBeam but with PROJECT_GRID.
+ */
+export function castLine(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+): boolean {
+  let flg = PROJECT.BEAM | PROJECT.GRID | PROJECT.KILL | PROJECT.THRU;
+  if (!source.isPlayer) flg |= PROJECT.PLAY;
+  return castProjection(state, cctx, source, target, dam, typ, flg, 0);
+}
+
+/**
+ * effect_handler_ALTER (L186): affect grids and objects, not monsters, with no
+ * damage (door/wall alteration). PROJECT_BEAM | GRID | ITEM (+THRU from
+ * project_aimed).
+ */
+export function castAlter(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  typ: number,
+): boolean {
+  let flg = PROJECT.BEAM | PROJECT.GRID | PROJECT.ITEM | PROJECT.THRU;
+  if (!source.isPlayer) flg |= PROJECT.PLAY;
+  return castProjection(state, cctx, source, target, 0, typ, flg, 0);
+}
+
+/** diameter_of_source for an arc/breath of the given width (arc.c geometry). */
+function arcDiameter(baseDiameter: number, degreesOfArc: number): number {
+  let d = baseDiameter;
+  if (degreesOfArc < 60) d = Math.trunc((d * 60) / degreesOfArc);
+  return d > 25 ? 25 : d;
+}
+
+/**
+ * effect_handler_ARC (L789): a cone from the caster. PROJECT_ARC | GRID | ITEM |
+ * KILL (+PLAY for a monster source). A radius of 0 means no fixed limit
+ * (z_info->max_range). The arc's energy source diameter starts at 4 and widens
+ * as the cone narrows, so a tight arc dissipates more slowly. degrees_of_arc is
+ * clamped to a minimum of 20.
+ */
+export function castArc(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  rad: number,
+  degreesOfArc: number,
+): boolean {
+  let flg = PROJECT.ARC | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  if (source.isMonster) flg |= PROJECT.PLAY;
+  const degrees = Math.max(degreesOfArc, 20);
+  const r = rad === 0 ? cctx.maxRange : rad;
+  const diameter = arcDiameter(4, degrees);
+  return castProjection(state, cctx, source, target, dam, typ, flg, r, degrees, diameter);
+}
+
+/**
+ * effect_handler_BREATH (L681): breathe an element in a cone. Like castArc, but
+ * a powerful monster breathes at full strength further out (source diameter
+ * 4 -> 6 before the arc-width widening). The damage (breath_dam) and the
+ * "You breathe X" message are the caller's (#19); a radius of 0 means
+ * z_info->max_range.
+ */
+export function castBreath(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  degreesOfArc: number,
+  opts: { radius?: number; powerful?: boolean } = {},
+): boolean {
+  let flg = PROJECT.ARC | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  if (source.isMonster) flg |= PROJECT.PLAY;
+  const degrees = Math.max(degreesOfArc, 20);
+  const rad = opts.radius && opts.radius > 0 ? opts.radius : cctx.maxRange;
+  /* Powerful monsters breathe at full strength further out. */
+  const baseDiameter = opts.powerful ? Math.trunc((4 * 3) / 2) : 4;
+  const diameter = arcDiameter(baseDiameter, degrees);
+  return castProjection(state, cctx, source, target, dam, typ, flg, rad, degrees, diameter);
+}
+
+/**
+ * effect_handler_SHORT_BEAM (L852): a fixed-length beam. PROJECT_ARC with
+ * degrees 0 and a positive radius is normalised to a beam by project(); the
+ * source diameter equals the radius so it is full strength for its whole
+ * length. The caller applies any player-level radius bonus (rad += lev / other).
+ */
+export function castShortBeam(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  rad: number,
+): boolean {
+  let flg = PROJECT.ARC | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  if (source.isMonster) flg |= PROJECT.PLAY;
+  const diameter = rad > 25 ? 25 : rad;
+  return castProjection(state, cctx, source, target, dam, typ, flg, rad, 0, diameter);
+}
+
+/**
+ * effect_handler_LASH (L899): a whip crack or spit - a finite-length beam at
+ * full strength for its whole length (source diameter = radius), affecting
+ * grids, objects, monsters AND the player (monsters lash the player).
+ * The caller computes the blow-derived damage and lash element.
+ */
+export function castLash(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  rad: number,
+): boolean {
+  const flg =
+    PROJECT.ARC |
+    PROJECT.GRID |
+    PROJECT.ITEM |
+    PROJECT.KILL |
+    PROJECT.PLAY;
+  const diameter = rad > 25 ? 25 : rad;
+  return castProjection(state, cctx, source, target, dam, typ, flg, rad, 0, diameter);
+}
+
+/**
+ * effect_handler_SPOT (L545): explode on the player's own grid, hitting the
+ * player (PROJECT_PLAY | SELF), grids, objects and monsters. The source
+ * diameter equals the radius. The caller applies any player-level radius bonus.
+ */
+export function castSpot(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  dam: number,
+  typ: number,
+  rad: number,
+): boolean {
+  const flg =
+    PROJECT.STOP |
+    PROJECT.PLAY |
+    PROJECT.GRID |
+    PROJECT.ITEM |
+    PROJECT.KILL |
+    PROJECT.SELF;
+  return castProjection(state, cctx, source, state.actor.grid, dam, typ, flg, rad, 0, rad);
+}
+
+/**
+ * effect_handler_SPHERE (L571): a ball from the player's grid with an explicit
+ * source diameter (full strength out to that diameter). Affects grids, objects
+ * and monsters, but not the player.
+ */
+export function castSphere(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  dam: number,
+  typ: number,
+  rad: number,
+  diameterOfSource: number,
+): boolean {
+  const flg = PROJECT.STOP | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  return castProjection(
+    state,
+    cctx,
+    source,
+    state.actor.grid,
+    dam,
+    typ,
+    flg,
+    rad,
+    0,
+    diameterOfSource,
+  );
+}
+
+/**
+ * effect_handler_STRIKE (L1001): drop a ball on the target from above
+ * (PROJECT_JUMP, no travel path). Affects grids, objects and monsters.
+ */
+export function castStrike(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  rad: number,
+): boolean {
+  const flg = PROJECT.JUMP | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  return castProjection(state, cctx, source, target, dam, typ, flg, rad);
+}
+
+/**
+ * effect_handler_STAR (L1032): a beam in each of the eight compass directions
+ * from the player. Affects grids and monsters. Returns whether any beam was
+ * noticed.
+ */
+export function castStar(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  dam: number,
+  typ: number,
+): boolean {
+  const flg = PROJECT.THRU | PROJECT.BEAM | PROJECT.GRID | PROJECT.KILL;
+  /* Describe unless blind (effect-handler-attack.c:1041). */
+  if (!(cctx.playerActor.timed[TMD.BLIND]! > 0)) {
+    cctx.worldEnv?.msg?.("Light shoots in all directions!");
+  }
+  let notice = false;
+  for (const off of DDGRID_DDD) {
+    const target = locSum(state.actor.grid, off);
+    if (castProjection(state, cctx, source, target, dam, typ, flg, 0)) notice = true;
+  }
+  return notice;
+}
+
+/**
+ * effect_handler_STAR_BALL (L1062): a ball in each of the eight compass
+ * directions from the player. Affects grids, objects and monsters.
+ */
+export function castStarBall(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  dam: number,
+  typ: number,
+  rad: number,
+): boolean {
+  const flg =
+    PROJECT.STOP | PROJECT.THRU | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  let notice = false;
+  for (const off of DDGRID_DDD) {
+    const target = locSum(state.actor.grid, off);
+    if (castProjection(state, cctx, source, target, dam, typ, flg, rad)) notice = true;
+  }
+  return notice;
+}
+
+/**
+ * project_touch (L112): a radius-1 (or given) ball centred on the player,
+ * affecting grids, objects and monsters but hidden from bolt visuals
+ * (PROJECT_HIDE). PROJECT_AWARE is set when the player is aware of the effect.
+ * The monster-source decoy / target-monster branches of effect_handler_TOUCH
+ * are deferred (#19); this is the base player-centred touch.
+ */
+export function castTouch(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  dam: number,
+  typ: number,
+  rad: number,
+  aware: boolean,
+): boolean {
+  let flg =
+    PROJECT.GRID | PROJECT.KILL | PROJECT.HIDE | PROJECT.ITEM | PROJECT.THRU;
+  if (aware) flg |= PROJECT.AWARE;
+  const r = rad > 0 ? rad : 1;
+  return castProjection(state, cctx, source, state.actor.grid, dam, typ, flg, r);
+}
+
+/**
+ * effect_handler_SWARM (L974): fire `num` non-jumping balls at the same target
+ * (targeting an absolute grid so a monster's death does not move the aim).
+ * Always player-sourced. Returns whether any shot was noticed.
+ */
+export function castSwarm(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  target: Loc,
+  dam: number,
+  typ: number,
+  rad: number,
+  num: number,
+): boolean {
+  const flg =
+    PROJECT.THRU | PROJECT.STOP | PROJECT.GRID | PROJECT.ITEM | PROJECT.KILL;
+  let notice = false;
+  for (let n = num; n > 0; n--) {
+    if (castProjection(state, cctx, source, target, dam, typ, flg, rad)) notice = true;
+  }
+  return notice;
+}
+
+/**
+ * effect_handler_PROJECT_LOS (L1088): apply a jump projection to every monster
+ * in line of sight of the origin. The projection source is always the player
+ * (damage is attributed to them), exactly as upstream. `excludeMonster` is the
+ * currently-acting monster (cave->mon_current), skipped so a monster casting
+ * this does not hit itself; `originGrid` defaults to the player's grid.
+ */
+export function castProjectLos(
+  state: GameState,
+  cctx: CastContext,
+  source: CastSource,
+  dam: number,
+  typ: number,
+  opts: {
+    originGrid?: Loc;
+    excludeMonster?: number;
+    useView?: boolean;
+    aware?: boolean;
+  } = {},
+): boolean {
+  /* PROJECT_LOS_AWARE (effect-handler-attack.c:1125-1159) adds PROJECT_AWARE
+     when the caster is aware and gates on square_isview (the player's field of
+     view) instead of los() from the origin. */
+  let flg = PROJECT.JUMP | PROJECT.KILL | PROJECT.HIDE;
+  if (opts.aware) flg |= PROJECT.AWARE;
+  const originGrid = opts.originGrid ?? state.actor.grid;
+  const exclude = opts.excludeMonster ?? 0;
+  let notice = false;
+  const max = monsterMax(state);
+  for (let i = 1; i < max; i++) {
+    const mon = state.monsters[i];
+    if (!mon) continue;
+    if (i === exclude) continue;
+    const visible = opts.useView
+      ? squareIsView(state.chunk, mon.grid)
+      : los(state.chunk, originGrid, mon.grid);
+    if (!visible) continue;
+    if (castProjection(state, cctx, source, mon.grid, dam, typ, flg, 0)) notice = true;
+  }
+  return notice;
+}