miaoda-game-grid-vision-core

Engine-independent line-of-sight, field-of-view, and persistent fog of war for rectangular and hex tile maps. Use it for roguelikes, tactics, stealth, and exploration rules; it computes visibility but does not render tiles or lighting.

pnpm add miaoda-game-grid-vision-core miaoda-game-grid-core

import { FogMap, hasLineOfSight, visibleTiles } from 'miaoda-game-grid-vision-core';

const isOpaque = (x: number, y: number) => map.get(x, y) === 'wall';
if (hasLineOfSight(enemy.tile, player.tile, isOpaque)) enemy.fireAt(player.tile);
const visible = visibleTiles(player.tile, 6, isOpaque);

const fog = new FogMap(map.width, map.height);
fog.reveal(player.tile, 6, isOpaque);
const state = fog.stateAt(x, y); // 'hidden' | 'explored' | 'visible'

lineTiles(a, b) returns the inclusive Bresenham line. hasLineOfSight ignores endpoints as blockers and checks only tiles between them. computeFOV/visibleTiles use a circular radius and may not be reciprocal between origins; use line of sight when reciprocity matters.

For an axial hex map, use the separate hex algorithms rather than passing topology into rectangular shadowcasting:

import { visibleHexes } from 'miaoda-game-grid-vision-core';
import { axialToOffset } from 'miaoda-game-grid-core';

const visible = visibleHexes(unit.hex, 6, (q, r) => hexMap.isWall(q, r));
fog.applyVisible(visible.map((hex) => axialToOffset(hex, 'odd-r')));

hexLine and hasHexLineOfSight are reciprocal, inclusive axial-grid queries. computeHexFOV/visibleHexes visit a cube-distance disk in stable ring order. Opaque target hexes remain visible and block lines behind them. The current LOS-based implementation is O(radius^3), intended for typical tactical and roguelike sight radii rather than very large real-time visibility fields.

Visibility policy

Use evaluateVisibility when gameplay visibility is attenuated by smoke, foliage, darkness, or limited perception points. It keeps that policy separate from strict LOS and works with either canonical line function:

import {
  evaluateVisibility,
  lineTiles,
  VISIBILITY_BLOCKER,
} from 'miaoda-game-grid-vision-core';

const result = evaluateVisibility({
  origin: guard.tile,
  target: player.tile,
  candidateTest: (_origin, target) => nearbyTargets.has(`${target.x},${target.y}`),
  coneTest: (origin, target) => isInsideGuardCone(origin, target),
  buildPath: lineTiles, // use hexLine for axial hexes
  pathTest: (path) => path.every((tile) => !hasClosedPortal(tile)),
  cellCost: (tile) => {
    if (isWall(tile)) return VISIBILITY_BLOCKER;
    return isSmoke(tile) ? 2 : 0;
  },
  budget: guard.perception,
});

candidateTest and coneTest run before line construction. pathTest then handles whole-path rules, while cellCost consumes the visibility budget from the first cell after the origin. A blocker target remains visible, but anything behind it returns reason: 'blocked'. Invalid negative/NaN costs fail immediately. The structured result distinguishes candidate rejection, cone rejection, path rejection, blockers, and budget exhaustion.

The evaluator does not perform geometric occlusion. Keep hasLineOfSight or hasHexLineOfSight as the authoritative wall/projectile query, and use the evaluator for gameplay perception policy. Cone geometry remains host/topology-specific; pixel angles and Phaser camera transforms do not enter this core.

FogMap remembers explored tiles. A new reveal demotes previously visible tiles to explored, while explored tiles never return to hidden. applyVisible accepts visibility computed by hex FOV, portals, or a server and preserves the same memory transitions. Use isVisible, isExplored, markExplored, and clear for common operations. Pair it with miaoda-game-lighting-core when visibility and illumination must be separate rules.