@xtia/grid 0.0.3 → 0.0.4

package/README.md

@@ -1,5 +1,7 @@
 # `Grid`
 
+**Alpha**: Some API details may change
+
 ## Summary
 
 A mutable 2D grid with efficient region views, spatial operations, and seamless interoperability with [Pipe2D](https://github.com/tiadrop/pipe2d). Store, edit, and transform 2D data with an ergonomic API designed for practical use.
@@ -46,14 +48,14 @@ const grid = Grid.from(source);
 
 ## Regions
 
-Use `grid.region(x, y, w, h)` to define a subgrid. The subgrid is a **view** into the parent; changes to the subgrid affect the parent and vice-versa.
+Use `grid.region(x, y, w, h)` to define a subgrid. The subgrid is **zero-copy view** into the parent; changes to the subgrid affect the parent and vice-versa.
 
 ```ts
 // game map with terrain
-const world = Grid.solid(100, 100, 0); // 0 = grass
+const world = Grid.solid(100, 100, "grass"); // Grid<string>
 
 // add a lake
-world.region(30, 30, 20, 20).fill(1); // 1 = water
+world.region(30, 30, 20, 20).fill("water");
 
 // add mountains around the lake with a circular mask
 const centre = world.cells.get(40, 40);
@@ -61,7 +63,7 @@ const mask = (x: number, y: number) => {
   const dist = Math.hypot(x - centre.x, y - centre.y);
   return dist > 12 && dist < 18; // mountain ring
 };
-world.fill(2, mask); // 2 = mountain
+world.fill("mountain", mask);
 
 // get a view of just the interesting area
 const lakeRegion = world.region(25, 25, 30, 30);
@@ -75,16 +77,15 @@ const lakeGrid = Grid.from(lakeRegion);
 `grid.map(read, write)` creates a **view** that reads and writes the parent through the provided transformation functions.
 
 ```ts
-const sprites = ["grass.png", "water.png", "mountain.png", "forest.png"];
 const spriteMap = world.map(
-	n => sprites[n],
-	s => sprites.indexOf(s)
+	type => type + ".png",
+	sprite => sprite.replace(/\.*/, '')
 );
 
-world.set(0, 0, 2); // modify the parent
+world.set(0, 0, "mountain"); // modify the parent
 console.log(spriteMap.get(0, 0)); // read the transformed view: "mountain.png"
 spriteMap.set(1, 0, "forest.png"); // modify the view
-console.log(world.get(1, 0)); // read the parent: 3
+console.log(world.get(1, 0)); // read the parent: "forest"
 ```
 
 For one-way read-mapping, use `grid.pipe` - a [Pipe2D](https://github.com/tiadrop/pipe2d) view into the grid's data.
@@ -95,9 +96,9 @@ For one-way read-mapping, use `grid.pipe` - a [Pipe2D](https://github.com/tiadro
 
 ```ts
 const topLeft = world.cells.get(0, 0);
-console.log(topLeft.value); // 2
+console.log(topLeft.value); // "mountain"
 
-topLeft.value = 3; // modifies the underlying data
+topLeft.value = "forest; // modifies the underlying data
 console.log(spriteMap.get(0, 0)); // now "forest.png";
 
 // navigate by offset
@@ -109,44 +110,63 @@ Cells provide methods for locational utilities such as pathfinding and visibilit
 
 Cells are unique to, owned by, and coordinated relative to the view that provided them. Their pathfinding and visibility mapping features are unaware of space outside of their view's bounds.
 
-### Path finding
+### (Everybody needs good) Neighbours
+
+`cell.getNeighbours(includeDiagonals?)` returns an array of Cells:
+
+```ts
+// derive a display number for clicked cells in Minesweeper
+const numOfAdjacentMines = clickedCell.getNeighbours(true)
+	.filter(cell => cell.value.isMine)
+	.length;
 ```
-const costs = [1, Infinity, Infinity, 2]; // grass=1, water/mountain=impassable, forest=2
+
+### Path finding
+```ts
+const costs = {
+	grass: 1,
+	water: Infinity,
+	mountain: Infinity,
+	forest: 2
+};
 
 const start = world.cells.get(5, 5);
 const destination = world.cells.get(90, 90);
 const path = start.findPath(
-	destination,
+	destination, // or simply [90, 90]
 	(cell) => costs[cell.value]
-); // Cell<number>[]
+); // Cell<string>[]
 ```
 
 ### Visibility mapping
 
 ```ts
+// createVisibilityMap(isClear);
 const visibility = start.createVisibilityMap(
-	cell => cell.value == 0 // anything except grass blocks vision
+	cell => cell.value === "grass" // anything except grass blocks vision
 );
 
-// any 2d source, including visibility maps, can be used as a mask
+// any 2d source, including visibility maps, can be used as a mask for paste/fill operations
 // paste(source: Source2D<T>, mask?: Source2D<boolean>)
-screenGrid.paste(spriteMap, visibility.map(v => v != Visibility.hidden));
+screenGrid.paste(spriteMap, visibility);
 
 // using pipe2d's convenience
-const mountainCells = world.cells.toFlatArrayXY().filter(c => c.value === 2);
+const mountainCells = world.cells.toFlatArrayXY().filter(c => c.value === "mountain");
 ```
 
 ### Reusing path data
 
-Use `cell.getPathMap(costFunc)` to create a Pipe2D of optimal paths from the parent cell. The grid space is explored once to produce an internal traversal map, and paths to individual cells are constructed form that data (and cached) when that pipe is queried.
+Use `cell.getPathMap(costFunc)` to create a Pipe2D of optimal paths from the parent cell. The grid space is explored once to produce an internal traversal map, and paths to individual cells are constructed from that data (and cached) when that pipe is queried.
 
 ```ts
-const pathMap = start.getPathMap(c => costs[c]);
+const pathMap = start.getPathMap(c => costs[c.value]);
 
 const pathToCentre = pathMap.get(50, 50);
 const pathToCorner = pathMap.get(99, 99);
 ```
 
+Unlike visibility maps, which are lazily evaluated according to the supplied `isWall` function *when the map is queried*, path maps necessarily reflect the underlying data *when the map is created*. This distinction is hinted through the `create*` vs `get*` naming.
+
 ## The storage layer
 
 `Grid` itself is an interface for reading and writing 2D data. `GridBase` - a subclass of `Grid` - maintains the actual storage of such data.

package/lib/grid.d.ts

@@ -18,6 +18,10 @@ type PathFindOptions<T> = {
 type CostMapOptions<T> = PathFindOptions<T> & {
     stopAt?: [number, number] | Cell<T>;
 };
+type VisibilityOptions = {
+    maxDistance?: number;
+    boundariesVisible?: boolean;
+};
 export declare enum TraversalType {
     cardinal = 0,
     diagonal = 1,
@@ -27,11 +31,6 @@ type CostFunc<T> = (cell: Cell<T>, context: {
     traversalType: TraversalType;
     from: Cell<T>;
 }) => number;
-export declare enum Visibility {
-    visible = 0,
-    hidden = 1,
-    wall = 2
-}
 export declare class Cell<T> {
     readonly x: number;
     readonly y: number;
@@ -49,7 +48,7 @@ export declare class Cell<T> {
         x: number;
         y: number;
     } | [number, number]): IterableIterator<Cell<T>>;
-    createVisibilityMap(isWall: (cell: Cell<T>) => boolean, maxDistance?: number): Pipe2D<Visibility>;
+    createVisibilityMap(isClear: (cell: Cell<T>) => boolean, options?: VisibilityOptions): Pipe2D<boolean>;
 }
 export declare class Grid<T> {
     readonly width: number;

package/lib/grid.js

@@ -6,12 +6,6 @@ export var TraversalType;
     TraversalType[TraversalType["diagonal"] = 1] = "diagonal";
     TraversalType[TraversalType["shortcut"] = 2] = "shortcut";
 })(TraversalType || (TraversalType = {}));
-export var Visibility;
-(function (Visibility) {
-    Visibility[Visibility["visible"] = 0] = "visible";
-    Visibility[Visibility["hidden"] = 1] = "hidden";
-    Visibility[Visibility["wall"] = 2] = "wall";
-})(Visibility || (Visibility = {}));
 export class Cell {
     constructor(x, y, gridView) {
         this.x = x;
@@ -175,26 +169,27 @@ export class Cell {
             }
         }
     }
-    createVisibilityMap(isWall, maxDistance = Infinity) {
+    createVisibilityMap(isClear, options = {}) {
+        var _a, _b;
+        const maxDistance = (_a = options.maxDistance) !== null && _a !== void 0 ? _a : Infinity;
+        const boundariesVisible = (_b = options.boundariesVisible) !== null && _b !== void 0 ? _b : true;
         return new Pipe2D(this.gridView.width, this.gridView.height, (x, y) => {
-            if (isWall(this))
-                return Visibility.hidden;
-            const distance = getDistance(this, { x, y });
-            if (distance > maxDistance) {
-                return Visibility.hidden;
+            if (!isClear(this)) {
+                return x === this.x && y === this.y ? boundariesVisible : false;
             }
-            for (const cell of this.getLineTo({ x, y })) {
-                if (isWall(cell)) {
-                    if (cell.x === this.x && cell.y === this.y) {
-                        continue;
-                    }
-                    if (cell.x === x && cell.y === y) {
-                        return Visibility.wall;
-                    }
-                    return Visibility.hidden;
+            if (maxDistance < Infinity) {
+                if (getDistance(this, { x, y }) > maxDistance) {
+                    return false;
                 }
             }
-            return Visibility.visible;
+            for (const cell of this.getLineTo({ x, y })) {
+                if (isClear(cell))
+                    continue;
+                return cell.x === x && cell.y === y
+                    ? boundariesVisible
+                    : false;
+            }
+            return true;
         });
     }
 }

package/lib/index.d.ts

@@ -1 +1 @@
-export { Grid, type GridBase, type Cell, TraversalType, Visibility } from "./grid.js";
+export { Grid, type GridBase, type Cell, TraversalType } from "./grid.js";

package/lib/index.js

@@ -1 +1 @@
-export { Grid, TraversalType, Visibility } from "./grid.js";
+export { Grid, TraversalType } from "./grid.js";

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {