@xtia/grid 0.0.4 → 0.0.6

package/README.md

@@ -22,7 +22,7 @@ npm i @xtia/grid
 ```
 
 ```ts
-import { Grid } from "@xtia/grid";
+import { Grid } from "@xtia/grid"; // ~4.8kb gzipped
 
 // initialise a 30x20 Grid<number> of 0's
 const numGrid = Grid.solid(30, 20, 0);
@@ -46,6 +46,34 @@ const source = imagePipe
 const grid = Grid.from(source);
 ```
 
+### Wrapping existing structures
+
+Use Grid's interface over any read/write 2D structure:
+
+```ts
+const gameMap = [
+	[0, 1, -1, 2],
+	[1, 0, 1, 0],
+	[-1, 1, 0, 2],
+	[2, 0, 2, -1]
+];
+
+// create a *live view* Grid over gameMap
+const grid = Grid.wrap(
+	gameMap[0].length, // width
+	gameMap.length, // height
+	(x, y) => gameMap[y][x], // get
+	(x, y, value) => gameMap[y][x] = value // set
+);
+
+// reading the grid = reading the source
+gameMap[0][0] = 50;
+console.log(grid.get(0, 0)); // 50
+// writing to the grid = writing to the source
+grid.set(3, 3, 100);
+console.log(gameMap[3][3]); // 100
+```
+
 ## 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.
@@ -74,12 +102,12 @@ 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 spriteMap = world.map(
 	type => type + ".png",
-	sprite => sprite.replace(/\.*/, '')
+	sprite => sprite.replace(/\..*/, '')
 );
 
 world.set(0, 0, "mountain"); // modify the parent
@@ -90,6 +118,20 @@ 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.
@@ -98,12 +140,12 @@ For one-way read-mapping, use `grid.pipe` - a [Pipe2D](https://github.com/tiadro
 const topLeft = world.cells.get(0, 0);
 console.log(topLeft.value); // "mountain"
 
-topLeft.value = "forest; // 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.
@@ -149,9 +191,6 @@ const visibility = start.createVisibilityMap(
 // 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
@@ -165,7 +204,7 @@ 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.
+Unlike visibility maps, which are lazily evaluated according to the supplied `isClear` function *when the map is queried* (but can be easily cached with `visMap.withCache()`), path maps use a relatively expensive traversal map that's created *when the map is created*. This distinction is hinted through the `create*` vs `get*` naming.
 
 ## The storage layer
 
@@ -173,4 +212,15 @@ Unlike visibility maps, which are lazily evaluated according to the supplied `is
 
 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

@@ -77,6 +77,7 @@ export declare class Grid<T> {
     static init<T>(width: number, height: number, initCell: (x: number, y: number) => T): GridBase<T>;
     static from<T>(source: Source2D<T>): GridBase<T>;
     static solid<T>(width: number, height: number, fillValue: T): GridBase<T>;
+    static wrap<T>(width: number, height: number, get: (x: number, y: number) => T, set: (x: number, y: number, value: T) => void, batch?: (callback: () => void) => void): Grid<T>;
 }
 export declare class GridBase<T> extends Grid<T> {
     private data;

package/lib/grid.js

@@ -132,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) {
@@ -314,6 +314,9 @@ export class Grid {
     static solid(width, height, fillValue) {
         return new GridBase(Pipe2D.solid(fillValue, width, height));
     }
+    static wrap(width, height, get, set, batch = cb => cb()) {
+        return new Grid(width, height, get, set, batch);
+    }
 }
 export class GridBase extends Grid {
     triggerEvent(name, data) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {
@@ -9,6 +9,7 @@
     },
     "./lib/*": null
   },
+  "keywords": ["grid", "game-dev", "pathfinding", "cellular-automata"],
   "scripts": {
     "build": "npx tsc",
     "test": "npx vitest run"