mrpas 2.1.1 → 2.2.0

package/README.md

@@ -8,7 +8,7 @@ Just use npm:
 npm install mrpas
 ```
 
-Or grab the code from the [repository](https://bitbucket.org/umbraprojekt/mrpas) and include it in your project.
+Or grab the code from the [repository](https://github.com/mingos777/mrpas) and include it in your project.
 
 ## Usage
 
@@ -28,9 +28,29 @@ ES modules can import the same named export:
 import { Mrpas } from "mrpas";
 ```
 
+Alternatively, instead of the callback, you can pass the map's transparency data as a flat array of `width * height` values, in row-major order (the cell at `x, y` is at index `y * width + x`). Truthy values denote transparent cells, falsy ones denote obstacles:
+
+```
+const transparency = new Uint8Array(20 * 20); // fill with 1 for transparent cells, 0 for obstacles
+
+const fov = new Mrpas(20, 20, transparency);
+```
+
+Any array-like object will do: a typed array, an array of booleans, numbers, etc. `Mrpas` keeps a reference to the array rather than a copy, so changes to the map (e.g. a door opening) only require updating the array's values. Cells outside the map are treated as obstacles.
+
+Using transparency data is usually faster than using a callback.
+
 ### Compute FOV
 
-Compute the field of view for any set of coordinates by calling the `Mrpas#compute()` method and passing it the origin coordinates, FOV calculation radius and two callbacks: one for determining whether a call has been marked as visible, and the othe for marking it as visible:
+Compute the field of view for any set of coordinates by calling the `Mrpas#compute()` method and passing it the origin coordinates, the FOV calculation radius and a callback for marking a cell as visible:
+
+```
+fov.compute(10, 10, 7, (x, y) => map[x][y].visible = true);
+```
+
+The callback is called once for every cell in the field of view. Cells that aren't visible are never reported, so remember to clear your map's visibility before computing the FOV again.
+
+Alternatively, you can pass two callbacks: one for determining whether a cell has been marked as visible, and the other for marking it as visible:
 
 ```
 fov.compute(
@@ -42,7 +62,9 @@ fov.compute(
 );
 ```
 
-To calculate the FOV on the entire map, regardless of radius, you may pass `Infinity` as the radius value. Just remember that the transparency callback (the one passed to the constructor) will need to account for this, returning `false` when a cell outside the map is checked.
+In this case, the visibility check callback must only report the cells marked as visible during the current computation: the visibility has to be cleared before each call. Otherwise, cells left visible by a previous computation can affect the result. Calling `compute()` with a single callback tracks visibility internally, which avoids this problem and is usually faster.
+
+To calculate the FOV on the entire map, regardless of radius, you may pass `Infinity` as the radius value. Just remember that a transparency callback (the one passed to the constructor) will need to account for this, returning `false` when a cell outside the map is checked. Transparency data handles this automatically.
 
 ### Map dimension changing
 
@@ -52,37 +74,38 @@ Should your map change dimensions, you can inform `Mrpas` about it by calling `M
 fov.setMapDimensions(40, 40);
 ```
 
+If you're using transparency data, the array's size and layout depend on the map dimensions, so create a new `Mrpas` instance with the new array instead.
+
 ### TypeScript
 
 MRPAS includes a TypeScript declaration file. It can be used in TypeScript projects without additional typings:
 
 ```
-import { Mrpas } from "mrpas";
+import { Mrpas, TransparencyData } from "mrpas";
 
-const fov: Mrpas = new Mrpas(20, 20, (x: number, y: number): boolean => map[x][y].transparent);
+const transparency: TransparencyData = new Uint8Array(20 * 20);
+const fov: Mrpas = new Mrpas(20, 20, transparency);
 
-fov.compute(
-    10,
-    10,
-    7,
-    (x: number, y: number): boolean => map[x][y].visible,
-    (x: number, y: number): void => map[x][y].visible = true
-);
+fov.compute(10, 10, 7, (x: number, y: number): void => {
+    map[x][y].visible = true;
+});
 ```
 
+The callback types, `IsTransparentFunc`, `IsVisibleFunc` and `SetVisibleFunc`, are exported as well.
+
 ## About MRPAS
 
 MRPAS, or [Mingos' Restrictive Precise Angle Shadowcasting](http://www.roguebasin.com/index.php?title=Restrictive_Precise_Angle_Shadowcasting) (Precise Angle Shadowcasting for short) is a field of view (FOV) computation algorithm. Given a 2D grid with a source point *S* and *n* points marked as obstacles, it will determine all points visible from *S*.
 
 To visualise this, let the following be a 2D grid of 20 by 20 points. The character `@` represents the field of view source, `#` characters represent obstacles. Cells with yellow background are in the source point's field of view:
 
-![fov](https://mingos.bitbucket.io/img/umbraprojekt/mrpas/fov.png)
+![fov](https://raw.githubusercontent.com/mingos777/mrpas/main/docs/fov.png)
 
 ### Real life uses
 
 This algorithm was conceived in the year 2008 for the purpose of being used in a [roguelike](http://www.roguebasin.com/index.php?title=What_a_roguelike_is) game. To this day, roguelikes remain the focus of MRPAS.
 
-The algorithm was originally written in C and was included in the roguelike library [libtcod](https://bitbucket.org/libtcod/libtcod). It also contained a C++ wrapper.
+The algorithm was originally written in C and was included in the roguelike library [libtcod](https://github.com/libtcod/libtcod). It also contained a C++ wrapper.
 
 Since 2008, MRPAS has been implemented [in various languages](http://www.roguebasin.com/index.php?title=Restrictive_Precise_Angle_Shadowcasting#Implementations), and has been successfully used in numerous roguelike games.
 
@@ -106,7 +129,7 @@ Considering the mathematics behind determining the FOV, the line of sight from A
 
 The algorithm's asymmetry can be seen on the following image, where the `.` character has been used to mark asymmetric points (if on yellow background, they can be seen from the source, but cannot see the source; if on black, the source is visible from them, but it cannot see them):
 
-![fov](https://mingos.bitbucket.io/img/umbraprojekt/mrpas/symmetry.png)
+![fov](https://raw.githubusercontent.com/mingos777/mrpas/main/docs/symmetry.png)
 
 On the above map, 1.6% of all points not containing an obstacle are asymmetric.
 
@@ -114,7 +137,7 @@ The percentage of asymmetric points is within the range of single digit numbers,
 
 For comparison, here's an "outdoor" map with 3.9% asymmetric points:
 
-![fov](https://mingos.bitbucket.io/img/umbraprojekt/mrpas/symmetry-outdoor.png)
+![fov](https://raw.githubusercontent.com/mingos777/mrpas/main/docs/symmetry-outdoor.png)
 
 ### Performance
 

package/dist/cjs/index.js

@@ -5,14 +5,17 @@ class Mrpas {
     mapWidth;
     mapHeight;
     isTransparent;
-    constructor(mapWidth, mapHeight, isTransparent) {
+    constructor(mapWidth, mapHeight, transparency) {
         this.mapWidth = mapWidth;
         this.mapHeight = mapHeight;
-        this.isTransparent = isTransparent;
+        this.isTransparent = typeof transparency === "function"
+            ? transparency
+            : (x, y) => x >= 0 && x < this.mapWidth && y >= 0 && y < this.mapHeight &&
+                !!transparency[y * this.mapWidth + x];
     }
     computeOctantY(deltaX, deltaY, data) {
-        const startSlopes = [];
-        const endSlopes = [];
+        const startSlopes = data.startSlopes;
+        const endSlopes = data.endSlopes;
         const minX = data.minX;
         const maxX = data.maxX;
         const minY = data.minY;
@@ -22,6 +25,8 @@ class Mrpas {
         const isTransparent = this.isTransparent;
         const isVisible = data.isVisible;
         const setVisible = data.setVisible;
+        const visibility = data.visibility;
+        const width = maxX - minX + 1;
         let iteration = 1;
         let totalObstacles = 0;
         let obstaclesInLastLine = 0;
@@ -53,11 +58,14 @@ class Mrpas {
                 transparencyChecked = false;
                 if (obstaclesInLastLine > 0) {
                     diagonalOpen = behindOpen;
-                    behindOpen = isVisible(x, y - deltaY) && isTransparent(x, y - deltaY);
+                    behindOpen = (visibility === null ? isVisible(x, y - deltaY) : visibility[(y - deltaY - minY) * width + x - minX] === 1) &&
+                        isTransparent(x, y - deltaY);
                     if (!behindOpen &&
                         !(processedCell > firstCell
                             ? diagonalOpen
-                            : isVisible(x - deltaX, y - deltaY) && isTransparent(x - deltaX, y - deltaY))) {
+                            : (visibility === null ? isVisible(x - deltaX, y - deltaY) : x - deltaX >= minX && x - deltaX <= maxX &&
+                                visibility[(y - deltaY - minY) * width + x - deltaX - minX] === 1) &&
+                                isTransparent(x - deltaX, y - deltaY))) {
                         visible = false;
                     }
                     else {
@@ -94,6 +102,9 @@ class Mrpas {
                 }
                 if (visible) {
                     setVisible(x, y);
+                    if (visibility !== null) {
+                        visibility[(y - minY) * width + x - minX] = 1;
+                    }
                     if (!transparencyChecked) {
                         cellTransparent = isTransparent(x, y);
                     }
@@ -114,8 +125,8 @@ class Mrpas {
         }
     }
     computeOctantX(deltaX, deltaY, data) {
-        const startSlopes = [];
-        const endSlopes = [];
+        const startSlopes = data.startSlopes;
+        const endSlopes = data.endSlopes;
         const minX = data.minX;
         const maxX = data.maxX;
         const minY = data.minY;
@@ -125,6 +136,8 @@ class Mrpas {
         const isTransparent = this.isTransparent;
         const isVisible = data.isVisible;
         const setVisible = data.setVisible;
+        const visibility = data.visibility;
+        const width = maxX - minX + 1;
         let iteration = 1;
         let totalObstacles = 0;
         let obstaclesInLastLine = 0;
@@ -156,11 +169,14 @@ class Mrpas {
                 transparencyChecked = false;
                 if (obstaclesInLastLine > 0) {
                     diagonalOpen = behindOpen;
-                    behindOpen = isVisible(x - deltaX, y) && isTransparent(x - deltaX, y);
+                    behindOpen = (visibility === null ? isVisible(x - deltaX, y) : visibility[(y - minY) * width + x - deltaX - minX] === 1) &&
+                        isTransparent(x - deltaX, y);
                     if (!behindOpen &&
                         !(processedCell > firstCell
                             ? diagonalOpen
-                            : isVisible(x - deltaX, y - deltaY) && isTransparent(x - deltaX, y - deltaY))) {
+                            : (visibility === null ? isVisible(x - deltaX, y - deltaY) : y - deltaY >= minY && y - deltaY <= maxY &&
+                                visibility[(y - deltaY - minY) * width + x - deltaX - minX] === 1) &&
+                                isTransparent(x - deltaX, y - deltaY))) {
                         visible = false;
                     }
                     else {
@@ -197,6 +213,9 @@ class Mrpas {
                 }
                 if (visible) {
                     setVisible(x, y);
+                    if (visibility !== null) {
+                        visibility[(y - minY) * width + x - minX] = 1;
+                    }
                     if (!transparencyChecked) {
                         cellTransparent = isTransparent(x, y);
                     }
@@ -220,17 +239,32 @@ class Mrpas {
         this.mapWidth = mapWidth;
         this.mapHeight = mapHeight;
     }
-    compute(originX, originY, radius, isVisible, setVisible) {
+    compute(originX, originY, radius, isVisibleOrSetVisible, setVisibleFunc) {
+        const minX = Math.max(0, originX - radius);
+        const minY = Math.max(0, originY - radius);
+        const maxX = Math.min(this.mapWidth - 1, originX + radius);
+        const maxY = Math.min(this.mapHeight - 1, originY + radius);
+        const width = maxX - minX + 1;
+        const visibility = setVisibleFunc === undefined
+            ? new Uint8Array(width * (maxY - minY + 1))
+            : null;
+        const setVisible = setVisibleFunc ?? isVisibleOrSetVisible;
+        if (visibility !== null) {
+            visibility[(originY - minY) * width + originX - minX] = 1;
+        }
         setVisible(originX, originY);
         const data = {
-            minX: Math.max(0, originX - radius),
-            minY: Math.max(0, originY - radius),
-            maxX: Math.min(this.mapWidth - 1, originX + radius),
-            maxY: Math.min(this.mapHeight - 1, originY + radius),
+            minX: minX,
+            minY: minY,
+            maxX: maxX,
+            maxY: maxY,
             originX: originX,
             originY: originY,
-            isVisible: isVisible,
-            setVisible: setVisible
+            isVisible: isVisibleOrSetVisible,
+            setVisible: setVisible,
+            visibility: visibility,
+            startSlopes: [],
+            endSlopes: []
         };
         this.computeOctantY(1, 1, data);
         this.computeOctantX(1, 1, data);

package/dist/esm/index.d.ts

@@ -1,13 +1,15 @@
 export type IsTransparentFunc = (x: number, y: number) => boolean;
 export type IsVisibleFunc = (x: number, y: number) => boolean;
 export type SetVisibleFunc = (x: number, y: number) => void;
+export type TransparencyData = ArrayLike<unknown>;
 export declare class Mrpas {
     private mapWidth;
     private mapHeight;
     private readonly isTransparent;
-    constructor(mapWidth: number, mapHeight: number, isTransparent: IsTransparentFunc);
+    constructor(mapWidth: number, mapHeight: number, transparency: IsTransparentFunc | TransparencyData);
     private computeOctantY;
     private computeOctantX;
     setMapDimensions(mapWidth: number, mapHeight: number): void;
+    compute(originX: number, originY: number, radius: number, setVisible: SetVisibleFunc): void;
     compute(originX: number, originY: number, radius: number, isVisible: IsVisibleFunc, setVisible: SetVisibleFunc): void;
 }

package/dist/esm/index.js

@@ -2,14 +2,17 @@ export class Mrpas {
     mapWidth;
     mapHeight;
     isTransparent;
-    constructor(mapWidth, mapHeight, isTransparent) {
+    constructor(mapWidth, mapHeight, transparency) {
         this.mapWidth = mapWidth;
         this.mapHeight = mapHeight;
-        this.isTransparent = isTransparent;
+        this.isTransparent = typeof transparency === "function"
+            ? transparency
+            : (x, y) => x >= 0 && x < this.mapWidth && y >= 0 && y < this.mapHeight &&
+                !!transparency[y * this.mapWidth + x];
     }
     computeOctantY(deltaX, deltaY, data) {
-        const startSlopes = [];
-        const endSlopes = [];
+        const startSlopes = data.startSlopes;
+        const endSlopes = data.endSlopes;
         const minX = data.minX;
         const maxX = data.maxX;
         const minY = data.minY;
@@ -19,6 +22,8 @@ export class Mrpas {
         const isTransparent = this.isTransparent;
         const isVisible = data.isVisible;
         const setVisible = data.setVisible;
+        const visibility = data.visibility;
+        const width = maxX - minX + 1;
         let iteration = 1;
         let totalObstacles = 0;
         let obstaclesInLastLine = 0;
@@ -50,11 +55,14 @@ export class Mrpas {
                 transparencyChecked = false;
                 if (obstaclesInLastLine > 0) {
                     diagonalOpen = behindOpen;
-                    behindOpen = isVisible(x, y - deltaY) && isTransparent(x, y - deltaY);
+                    behindOpen = (visibility === null ? isVisible(x, y - deltaY) : visibility[(y - deltaY - minY) * width + x - minX] === 1) &&
+                        isTransparent(x, y - deltaY);
                     if (!behindOpen &&
                         !(processedCell > firstCell
                             ? diagonalOpen
-                            : isVisible(x - deltaX, y - deltaY) && isTransparent(x - deltaX, y - deltaY))) {
+                            : (visibility === null ? isVisible(x - deltaX, y - deltaY) : x - deltaX >= minX && x - deltaX <= maxX &&
+                                visibility[(y - deltaY - minY) * width + x - deltaX - minX] === 1) &&
+                                isTransparent(x - deltaX, y - deltaY))) {
                         visible = false;
                     }
                     else {
@@ -91,6 +99,9 @@ export class Mrpas {
                 }
                 if (visible) {
                     setVisible(x, y);
+                    if (visibility !== null) {
+                        visibility[(y - minY) * width + x - minX] = 1;
+                    }
                     if (!transparencyChecked) {
                         cellTransparent = isTransparent(x, y);
                     }
@@ -111,8 +122,8 @@ export class Mrpas {
         }
     }
     computeOctantX(deltaX, deltaY, data) {
-        const startSlopes = [];
-        const endSlopes = [];
+        const startSlopes = data.startSlopes;
+        const endSlopes = data.endSlopes;
         const minX = data.minX;
         const maxX = data.maxX;
         const minY = data.minY;
@@ -122,6 +133,8 @@ export class Mrpas {
         const isTransparent = this.isTransparent;
         const isVisible = data.isVisible;
         const setVisible = data.setVisible;
+        const visibility = data.visibility;
+        const width = maxX - minX + 1;
         let iteration = 1;
         let totalObstacles = 0;
         let obstaclesInLastLine = 0;
@@ -153,11 +166,14 @@ export class Mrpas {
                 transparencyChecked = false;
                 if (obstaclesInLastLine > 0) {
                     diagonalOpen = behindOpen;
-                    behindOpen = isVisible(x - deltaX, y) && isTransparent(x - deltaX, y);
+                    behindOpen = (visibility === null ? isVisible(x - deltaX, y) : visibility[(y - minY) * width + x - deltaX - minX] === 1) &&
+                        isTransparent(x - deltaX, y);
                     if (!behindOpen &&
                         !(processedCell > firstCell
                             ? diagonalOpen
-                            : isVisible(x - deltaX, y - deltaY) && isTransparent(x - deltaX, y - deltaY))) {
+                            : (visibility === null ? isVisible(x - deltaX, y - deltaY) : y - deltaY >= minY && y - deltaY <= maxY &&
+                                visibility[(y - deltaY - minY) * width + x - deltaX - minX] === 1) &&
+                                isTransparent(x - deltaX, y - deltaY))) {
                         visible = false;
                     }
                     else {
@@ -194,6 +210,9 @@ export class Mrpas {
                 }
                 if (visible) {
                     setVisible(x, y);
+                    if (visibility !== null) {
+                        visibility[(y - minY) * width + x - minX] = 1;
+                    }
                     if (!transparencyChecked) {
                         cellTransparent = isTransparent(x, y);
                     }
@@ -217,17 +236,32 @@ export class Mrpas {
         this.mapWidth = mapWidth;
         this.mapHeight = mapHeight;
     }
-    compute(originX, originY, radius, isVisible, setVisible) {
+    compute(originX, originY, radius, isVisibleOrSetVisible, setVisibleFunc) {
+        const minX = Math.max(0, originX - radius);
+        const minY = Math.max(0, originY - radius);
+        const maxX = Math.min(this.mapWidth - 1, originX + radius);
+        const maxY = Math.min(this.mapHeight - 1, originY + radius);
+        const width = maxX - minX + 1;
+        const visibility = setVisibleFunc === undefined
+            ? new Uint8Array(width * (maxY - minY + 1))
+            : null;
+        const setVisible = setVisibleFunc ?? isVisibleOrSetVisible;
+        if (visibility !== null) {
+            visibility[(originY - minY) * width + originX - minX] = 1;
+        }
         setVisible(originX, originY);
         const data = {
-            minX: Math.max(0, originX - radius),
-            minY: Math.max(0, originY - radius),
-            maxX: Math.min(this.mapWidth - 1, originX + radius),
-            maxY: Math.min(this.mapHeight - 1, originY + radius),
+            minX: minX,
+            minY: minY,
+            maxX: maxX,
+            maxY: maxY,
             originX: originX,
             originY: originY,
-            isVisible: isVisible,
-            setVisible: setVisible
+            isVisible: isVisibleOrSetVisible,
+            setVisible: setVisible,
+            visibility: visibility,
+            startSlopes: [],
+            endSlopes: []
         };
         this.computeOctantY(1, 1, data);
         this.computeOctantX(1, 1, data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mrpas",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "A Field of View (FOV) computation algorithm.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -19,7 +19,8 @@
     "build": "npm run build:esm && npm run build:cjs",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:cjs": "tsc -p tsconfig.cjs.json",
-    "watch": "tsc --watch -p tsconfig.esm.json"
+    "watch": "tsc --watch -p tsconfig.esm.json",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",