core/agent.ts

import { Board } from "./board.ts";
import { Cell } from "./cell.ts";
import { Color } from "./color.ts";
import { Direction } from "./direction.ts";
import { GameEvent } from "./game-event.ts";
import { Item } from "./item.ts";
import { Piece } from "./piece.ts";

/**
 * Base class for all agent types.
 *
 * Agents exclusively occupy a cell. They may be animate (monsters, NPCs) 
 * or static (boulders, pillars). All callbacks are no-ops by default.
 */
export class Agent extends Piece {
  onColorEvent(event: GameEvent, color: Color, cell: Cell) { }
  /**
   * 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.
   */
  changeHealth(value: number): number {
    return 0;
  }

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

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

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

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

  /**
   * This agent has died.
   */
  onDie(event: GameEvent, cell: 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).
   */
  onTurn(event: GameEvent, board: Board, cell: Cell) { }
}