Appearance
Grids and spatial queries
Two helpers for where things are on the ground: finding the entities within reach of a point, and turning the cells of a board into world points and back. Distances are measured between world positions, so ChildOf children count where they are drawn.
Entities near a point
SpatialIndex finds the entities with a trait whose world position is within radius of a world-space point, nearest first, e.g. the enemies a tower reaches or the vehicles near a stop. It keeps a hash grid, so it stays fast for thousands of entities and many queries a frame:
ts
import { SpatialIndex } from "@pawnjs/core";
engine.use(new SpatialIndex({ cellSize: 2 })); // optional; plugin() installs one
const [target] = engine.plugin(SpatialIndex).near(tower, 2.5, Enemy);- The grid of a trait is built on its first query in a frame and reused by the frame's later queries, so positions are as of that first query. Entities that get or lose the trait count at once.
cellSize(2 by default) works best close to the usual query radius. A radius much wider than a cell checks every entity.- With 100,000 entities and 100 queries a frame,
neartakes about 33 ms where checking every entity takes about 1.2 s (bun run benchinpackages/core, headless).
Grids
Grid maps the cells of a board on the ground (the xz plane) to world points and back, such as the tiles of a game or the slots of a warehouse. Columns run along x, rows along z, and the grid is centered on center:
ts
import { Grid } from "@pawnjs/core";
const grid = new Grid({ columns: 12, rows: 8, size: 1 });
tower.set(Position, grid.toWorld(3, 2, 0.5)); // middle of the cell, y 0.5
grid.fromWorld(hit.point); // { column, row }, or undefined off the grid
grid.contains(12, 0); // false
grid.line([{ column: 0, row: 1 }, { column: 3, row: 1 }]); // 4 cells
for (const { column, row } of grid.cells()) spawnTile(column, row);line(corners) lists the cells along straight lines (across, down or diagonal) through corner cells, such as a road; key(column, row) gives "column,row" for maps and sets. A Grid is plain math and spawns nothing.