@statedelta-apex/board-kit

O kit de serviços espaciais sobre o Board — helpers de grid/voxel e movement models que estendem o que dá pra computar sobre um board-state. Pathfinding é o primeiro módulo (sobre @statedelta/graph-core); visibilidade, regiões, terreno e propagação de campo vêm a seguir.

Filosofia

O Board é o repositório (estado + índice espacial). Este pacote é a camada de serviço por cima — como se estendesse os métodos do board. Opera sobre predicados abstratos (isBlocked, isSolid), então funciona em qualquer grid discreto, 2D e 3D, sem acoplar a um Board concreto.

A busca em grafo genérica mora no @statedelta/graph-core (reusada também pelo GraphState) e é re-exportada aqui — um import só pra trabalhar com o board.

Instalação

pnpm add @statedelta-apex/board-kit

Módulos

• nav (pathfinding) — aStar/dijkstra/bfs/… (do graph) + os movement models de grid.
• terreno / movimento — stepNeighbors (mob), climbNeighbors (aranha), gridHeuristic.
• execução — createWalker (tick-stepper, 1 bloco por tick).
• (roadmap) visibility (FOV/raycast), regions (componentes/conexões), field (luz/influence).

Movement models

stepNeighbors — mob normal (gravidade)

De um bloco feet, os passos legais de 1 bloco: lateral, subir 1 ou descer 1, exigindo clearance (a coluna do agente livre) e suporte (chão embaixo). O mesmo stepNeighbors planeja (alimenta o A*) e valida a execução.

import {
  aStar,
  stepNeighbors,
  vecKey,
  gridHeuristic,
} from "@statedelta-apex/board-kit";

const step = (feet) =>
  stepNeighbors(feet, {
    isBlocked: (c) => world.isOccupied(c),
    isSolid: (c) => world.isOccupied(c),
    height: 2, // agente de 2 de altura
    maxStepUp: 1,
    maxStepDown: 1,
  });

const { path } = aStar(start, goal, {
  neighbors: step,
  key: vecKey,
  heuristic: gridHeuristic("manhattan"),
});

climbNeighbors — aranha (vertical livre com guia)

Movimento vertical livre desde que haja um bloco-guia pra se agarrar (célula adjacente a um sólido). Escala paredes que o stepNeighbors não sobe.

Mesmo Board, movement models diferentes = acessos diferentes: um mob (sobe 1) não alcança o topo de um penhasco de 3 blocos; uma aranha sobe a parede.

Execução — createWalker

Avança por um caminho planejado 1 nó por tick, sem interpolação/tempo. É como o teste Minecraft executa o caminho.

import { createWalker } from "@statedelta-apex/board-kit";

const walker = createWalker(path);
while (!walker.done) board.moveTo(mob.id, walker.tick());

Tipos Exportados

import {
  // grid / movimento
  vecKey,
  gridHeuristic,
  stepNeighbors,
  climbNeighbors,
  createWalker,
  // busca (re-exportada de @statedelta/graph-core)
  aStar,
  dijkstra,
  greedyBestFirst,
  bfs,
  bidirectional,
  flowField,
  reachable,
  floodFill,
} from "@statedelta-apex/board-kit";
import type {
  Vec,
  GridMetric,
  StepOptions,
  ClimbOptions,
  Walker,
  SearchResult,
  PathOptions,
} from "@statedelta-apex/board-kit";

Documentação

• docs/ARCHITECTURE.md — internals: a pipeline de pathfinding, os movement models (stepNeighbors/climbNeighbors), o tick-stepper, e a composição agnóstica com graph-core.

License

MIT