@xtia/grid 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,176 @@
+# `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.
+
+## Features
+
+- **Mutable 2D storage** with type safety
+- **Zero-copy region views** - edit or provide subgrids and transformation layers without copying
+- **Spatial operations** - fill, paste, flood fill, pathfinding
+- **Pipe2D integration** - materialise pipes, get pipe views
+- **Consistent API** - for grids and regions
+- **Mask support** - apply operations to arbitrary shapes
+
+## Example
+
+```
+npm i @xtia/grid
+```
+
+```ts
+import { Grid } from "@xtia/grid";
+
+// initialise a 30x20 Grid<number> of 0's
+const numGrid = Grid.solid(30, 20, 0);
+
+// change a value
+numGrid.set(3, 3, 50);
+
+// initialise a chessboard
+const chessGrid = Grid.init(8, 8, (x, y) => 
+  (x + y) % 2 === 0 ? 'black' : 'white'
+);
+
+// read a value
+const colour = chessGrid.get(4, 5);
+
+// initialise a grid from a Pipe2D
+const source = imagePipe
+	.crop(10, 10, 64, 64)
+	.scale(.5)
+	.rotateLeft();
+const grid = Grid.from(source);
+```
+
+## Regions
+
+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, "grass"); // Grid<string>
+
+// add a lake
+world.region(30, 30, 20, 20).fill("water");
+
+// add mountains around the lake with a circular mask
+const centre = world.cells.get(40, 40);
+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("mountain", mask);
+
+// get a view of just the interesting area
+const lakeRegion = world.region(25, 25, 30, 30);
+
+// do we want a distinct, self-contained copy of the region?
+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.
+
+```ts
+const spriteMap = world.map(
+	type => type + ".png",
+	sprite => sprite.replace(/\.*/, '')
+);
+
+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: "forest"
+```
+
+For one-way read-mapping, use `grid.pipe` - a [Pipe2D](https://github.com/tiadrop/pipe2d) view into the grid's data.
+
+## 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); // "mountain"
+
+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
+```
+
+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.
+
+### (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;
+```
+
+### 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, // or simply [90, 90]
+	(cell) => costs[cell.value]
+); // Cell<string>[]
+```
+
+### Visibility mapping
+
+```ts
+// createVisibilityMap(isClear);
+const visibility = start.createVisibilityMap(
+	cell => cell.value === "grass" // anything except grass blocks vision
+);
+
+// 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);
+
+// using pipe2d's convenience
+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 from that data (and cached) when that pipe is queried.
+
+```ts
+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)`.

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;
@@ -64,8 +63,8 @@ export declare class Grid<T> {
     get(x: number, y: number): T;
     set(x: number, y: number, value: T): void;
     trySet(x: number, y: number, value: T): boolean;
-    fill(value: T, mask?: Source2D<boolean>): void;
-    paste(x: number, y: number, source: Source2D<T>, mask?: Source2D<boolean>): void;
+    fill(value: T, mask?: Source2D<boolean> | GetXYFunc<boolean>): void;
+    paste(x: number, y: number, source: Source2D<T>, mask?: Source2D<boolean> | GetXYFunc<boolean>): void;
     [Symbol.iterator](): IterableIterator<{
         x: number;
         y: 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;
         });
     }
 }
@@ -235,10 +230,15 @@ export class Grid {
         return true;
     }
     fill(value, mask) {
+        const maskSource = typeof mask == "function" ? {
+            width: this.width,
+            height: this.height,
+            get: mask
+        } : mask;
         this.batchUpdate(() => {
             for (let y = 0; y < this.height; y++) {
                 for (let x = 0; x < this.width; x++) {
-                    if (mask && !mask.get(x, y))
+                    if (maskSource && !maskSource.get(x, y))
                         continue;
                     this.trySet(x, y, value);
                 }
@@ -246,13 +246,18 @@ export class Grid {
         });
     }
     paste(x, y, source, mask) {
+        const maskSource = typeof mask == "function" ? {
+            width: this.width,
+            height: this.height,
+            get: mask
+        } : mask;
         const cachedSource = new GridBase(source);
         this.batchUpdate(() => {
             for (let oy = 0; oy < source.height; oy++) {
                 for (let ox = 0; ox < source.width; ox++) {
                     const tx = ox + x;
                     const ty = oy + y;
-                    if (mask && !mask.get(tx, ty))
+                    if (maskSource && !maskSource.get(tx, ty))
                         continue;
                     this.trySet(tx, ty, cachedSource.get(ox, oy));
                 }

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,6 +1,6 @@
 {
-  "version": "0.0.2",
-  "description": "2D store and utilities",
+  "version": "0.0.4",
+  "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {
     ".": {