@xtia/grid 0.0.10 → 0.0.12

package/README.md

@@ -91,7 +91,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("mountain", mask);
+world.writeMask(mask).fill("mountain");
 
 // get a view of just the interesting area
 const lakeRegion = world.region(25, 25, 30, 30);
@@ -203,9 +203,8 @@ 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, 0, 0, visibility);
+// writeMask() creates a live view that only allows writes at positions allowed by the mask Source2D/function
+screenGrid.writeMask(visibility).paste(spriteMap, 0, 0);
 ```
 
 ### Reusing path data
@@ -234,8 +233,17 @@ We can perform batched updates, suppressing the 'change' event until a process c
 Pipe2D makes it easy to save and restore grid data:
 
 ```ts
-const saved = world.pipe.toFlatArrayXY(); // ["mountain", "forest", "grass", ...]
+const snapshot = world.pipe.stash();
 
-const restoredPipe = Pipe2D.fromFlatArrayXY(saved);
-const restored = Grid.from(restoredPipe);
-```
+const restored = Grid.from(snapshot);
+// or paste it to an existing grid
+world.paste(snapshot);
+```
+
+For persistent storage or transmission, Pipe2D can export as array:
+
+```ts
+const saved = snapshot.toFlatArrayXY(); // ["mountain", "forest", "grass", ...]
+
+const restoredSnapshot = Pipe2D.fromFlatArrayXY(saved);
+```

package/lib/grid.d.ts

@@ -64,8 +64,9 @@ 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> | GetXYFunc<boolean>): void;
-    paste(source: Source2D<T>, x?: number, y?: number, mask?: Source2D<boolean> | GetXYFunc<boolean>): void;
+    fill(value: T): void;
+    paste(source: Source2D<T>, x?: number, y?: number): void;
+    writeMask(mask: Source2D<boolean> | GetXYFunc<boolean>): Grid<T>;
     [Symbol.iterator](): IterableIterator<{
         x: number;
         y: number;
@@ -75,6 +76,7 @@ export declare class Grid<T> {
     combine<U, R>(aux: Source2D<U>, cb: (source: T, aux: U) => R): GridBase<R>;
     map<U>(read: (initial: T, x: number, y: number) => U, write: (local: U, x: number, y: number) => T): Grid<U>;
     region(x: number, y: number, width: number, height: number): Grid<T>;
+    scroll(xDelta: number, yDelta: number, fill: T): this;
     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>;

package/lib/grid.js

@@ -218,17 +218,29 @@ export class Grid {
             return new Cell(x, y, this);
         }).strict().withCache();
         this.pipe = new Pipe2D(this);
+        if (!Number.isInteger(width) || !Number.isInteger(height)) {
+            throw new Error(`Grid width & height must be integer; got (${width} x ${height})`);
+        }
+        if (width < 0 || height < 0) {
+            throw new Error(`Grid width/height may not be less than 0; got (${width} x ${height})`);
+        }
     }
     batchUpdate(fn) {
         this.batch(fn);
     }
     get(x, y) {
+        if (!Number.isInteger(x) || !Number.isInteger(y)) {
+            throw new Error(`Coordinates must be integer; got (${x}, ${y})`);
+        }
         if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
             throw new RangeError("Coordinates out of bounds");
         }
         return this.parentGet(x, y);
     }
     set(x, y, value) {
+        if (!Number.isInteger(x) || !Number.isInteger(y)) {
+            throw new Error(`Coordinates must be integer; got (${x}, ${y})`);
+        }
         if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
             throw new RangeError("Coordinates out of bounds");
         }
@@ -245,41 +257,36 @@ export class Grid {
         this.set(x, y, value);
         return true;
     }
-    fill(value, mask) {
-        const maskSource = typeof mask == "function" ? {
-            width: this.width,
-            height: this.height,
-            get: mask
-        } : mask;
+    fill(value) {
         this.batchUpdate(() => {
             for (let y = 0; y < this.height; y++) {
                 for (let x = 0; x < this.width; x++) {
-                    if (maskSource && !maskSource.get(x, y))
-                        continue;
                     this.trySet(x, y, value);
                 }
             }
         });
     }
-    paste(source, x = 0, y = 0, mask) {
-        const maskSource = typeof mask == "function" ? {
-            width: this.width,
-            height: this.height,
-            get: mask
-        } : mask;
-        const cachedSource = new GridBase(source);
+    paste(source, x = 0, y = 0) {
+        const cachedSource = new Pipe2D(source).stash();
         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 (maskSource && !maskSource.get(tx, ty))
-                        continue;
-                    this.trySet(tx, ty, cachedSource.get(ox, oy));
+                    this.trySet(ox + x, oy + y, cachedSource.get(ox, oy));
                 }
             }
         });
     }
+    writeMask(mask) {
+        const getMask = typeof mask == "function"
+            ? mask
+            : (x, y) => mask.get(x, y);
+        return new Grid(this.width, this.height, this.parentGet, (x, y, v) => {
+            const writable = getMask(x, y);
+            if (writable) {
+                this.set(x, y, v);
+            }
+        }, cb => this.batch(cb));
+    }
     *[Symbol.iterator]() {
         for (let y = 0; y < this.height; y++) {
             for (let x = 0; x < this.width; x++) {
@@ -309,12 +316,37 @@ export class Grid {
         return new Grid(this.width, this.height, (x, y) => read(this.parentGet(x, y), x, y), (x, y, value) => this.parentSet(x, y, write(value, x, y)), fn => this.batch(fn));
     }
     region(x, y, width, height) {
+        if (!Number.isInteger(x) || !Number.isInteger(y) || !Number.isInteger(width) || !Number.isInteger(height)) {
+            throw new Error(`Region boundaries must be integer; got (${x}, ${y}), (${width} x ${height})`);
+        }
+        if (x < 0 || y < 0 || x + width > this.width || y + height > this.height) {
+            throw new Error("Requested region exceeds the parent's bounds");
+        }
         return new Grid(width, height, (tx, ty) => {
             return this.parentGet(tx + x, ty + y);
         }, (tx, ty, value) => {
             this.parentSet(tx + x, ty + y, value);
         }, fn => this.batch(fn));
     }
+    scroll(xDelta, yDelta, fill) {
+        if (!Number.isInteger(xDelta) || !Number.isInteger(yDelta)) {
+            throw new Error(`Scroll offsets must be integer; got (${xDelta}, ${yDelta})`);
+        }
+        this.paste(this, xDelta, yDelta);
+        if (xDelta > 0) {
+            this.region(0, 0, xDelta, this.height).fill(fill);
+        }
+        else if (xDelta < 0) {
+            this.region(this.width + xDelta, 0, -xDelta, this.height).fill(fill);
+        }
+        if (yDelta > 0) {
+            this.region(0, 0, this.width, yDelta).fill(fill);
+        }
+        else if (yDelta < 0) {
+            this.region(0, this.height + yDelta, this.width, -yDelta).fill(fill);
+        }
+        return this;
+    }
     static init(width, height, initCell) {
         return new GridBase({
             width,

package/package.json

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