@xtia/grid 0.0.3 → 0.0.5

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.
@@ -20,7 +22,7 @@ npm i @xtia/grid
 ```
 
 ```ts
-import { Grid } from "@xtia/grid";
+import { Grid } from "@xtia/grid"; // ~5.3kb gzipped
 
 // initialise a 30x20 Grid<number> of 0's
 const numGrid = Grid.solid(30, 20, 0);
@@ -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);
@@ -72,85 +74,125 @@ const lakeGrid = Grid.from(lakeRegion);
 
 ## Transformation Layers
 
-`grid.map(read, write)` creates a **view** that reads and writes the parent through the provided transformation functions.
+`grid.map(read, write)` creates a **zero-copy 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.
 
+```ts
+// create a one-way, player-centred sprite map
+const viewport = world.pipe
+	.oob("mountain")
+	.map(t => t + ".png")
+	.crop(playerX - 5, playerY - 5, 10, 10);
+
+// or get a list of locations of cells with mountains
+const mountainCells = world.cells.toFlatArrayXY()
+	.filter(cell => cell.value === "mountain")
+	.map(cell => [cell.x, cell.y]);
+
+```
+
 ## Cell interface
 
 `grid.cells` provides a Pipe2D, for convenient transformation, of live-view interfaces relating to positions in the grid.
 
 ```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
 const adjacentCell = topLeft.look(1, 0);
-console.log(adjacentCell.x, adjacentCell.y); // 1, 0
+console.log(adjacentCell?.x, adjacentCell?.y); // 1, 0
 ```
 
 Cells provide methods for locational utilities such as pathfinding and visibility mapping.
 
 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));
-
-// using pipe2d's convenience
-const mountainCells = world.cells.toFlatArrayXY().filter(c => c.value === 2);
+screenGrid.paste(spriteMap, visibility);
 ```
 
 ### 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.
 
 Although the Grid factory methods (`Grid.solid()`, `Grid.from()`, `Grid.init()`) return a `GridBase<T>`, the mental model is that we're simply working with `Grid`s, therefore those factory methods live on `Grid`. The only API distinction is that `GridBase` provides a 'change' event, via `grid.on("change", handler)`.
 
-You can perform batched updates, holding off the 'change' event until the batch process concludes, with `grid.batchUpdate(callback)`.
+You can perform batched updates, holding off the 'change' event until the batch process concludes, with `grid.batchUpdate(callback)`.
+
+## Save and load
+
+Pipe2D makes it easy to save and restore grid data:
+
+```ts
+const saved = world.pipe.toFlatArrayXY(); // ["mountain", "forest", "grass", ...]
+
+const restoredPipe = Pipe2D.fromFlatArrayXY(saved);
+const restored = Grid.from(restoredPipe);
+```

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;
@@ -138,7 +132,7 @@ export class Cell {
                 return path;
             });
         }
-        return this.gridView.cells.map((c => { var _a; return (_a = costs.get(c)) !== null && _a !== void 0 ? _a : Infinity; }))
+        return this.gridView.cells.map(costs, () => Infinity)
             .strict();
     }
     *getLineTo(target) {
@@ -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.5",
   "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {