core/agent.js

import { Piece } from "./piece.js";

/**
 * Base class for all agent types.
 *
 * Agents exclusively occupy a cell (one agent per cell at most). They may be
 * animate (monsters, NPCs) or static (boulders, pillars). All callbacks are
 * no-ops by default.
 */
export class Agent extends Piece {
  /**
   * Apply a health change to this agent.
   * For the player: adjusts HP and returns current HP.
   * For other agents: used as a percentage-hit-chance adjustment; returns 0 on death.
   * @param {number} value - positive = heal, negative = damage
   * @returns {number}
   */
  changeHealth(value) {
    return 0;
  }

  /**
   * Can this agent enter the destination terrain from its current cell?
   * Mirrors Terrain.canEnter — both must return true for movement to occur.
   * @param {Direction} direction
   * @param {Cell} from
   * @param {Cell} to
   * @returns {boolean}
   */
  canEnter(direction, from, to) {
    return true;
  }

  /**
   * This agent has collided with another agent (player↔agent only; agents
   * do not collide with each other).
   * @param {GameEvent} event
   * @param {Cell} attackerCell
   * @param {Cell} agentLoc
   * @param {Agent} agent
   */
  onHit(event, attackerCell, agentLoc, agent) {}

  /**
   * This agent has been hit by another agent.
   * Typically cancels the mover's move event unless this agent steps aside.
   * @param {GameEvent} event
   * @param {Cell} agentLoc
   * @param {Agent} agent
   * @param {Direction} dir
   */
  onHitBy(event, agentLoc, agent, dir) {}

  /**
   * This agent has been hit by a thrown or wielded item.
   * @param {GameEvent} event
   * @param {Cell} itemLoc
   * @param {Item} item
   * @param {Direction} dir
   */
  onHitByItem(event, itemLoc, item, dir) {}

  /**
   * This agent has died.
   * @param {GameEvent} event
   * @param {Cell} cell
   */
  onDie(event, cell) {}

  /**
   * Called once per game turn so the agent can take an action (move, attack, etc.).
   * Non-player agents implement AI here. No-op by default (static agents).
   * @param {GameEvent} event
   * @param {Board} board
   * @param {Cell} cell
   */
  onTurn(event, board, cell) {}
}