From 9d727de0f00961fc9da12378800e6d92af69f940 Mon Sep 17 00:00:00 2001
From: admon84 <admon84@users.noreply.github.com>
Date: Fri, 1 Dec 2023 20:59:07 -0700
Subject: [PATCH] feat: add RoomTerrain.getRawBuffer() (#247)

* feat: add RoomTerrain.getRawBuffer()

* fix: incorporate changes recommended by @DiamondMofend and update tests

* fix: replace TypedArray helper with inline type
---
 dist/index.d.ts       | 23 +++++++++++++++++++++++
 dist/screeps-tests.ts | 27 ++++++++++++++++++++++++++-
 src/helpers.ts        |  2 ++
 src/room-terrain.ts   | 21 +++++++++++++++++++++
 4 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/dist/index.d.ts b/dist/index.d.ts
index b532efae..359e968e 100644
--- a/dist/index.d.ts
+++ b/dist/index.d.ts
@@ -2032,7 +2032,9 @@ declare namespace Tag {
         private [OpaqueTagSymbol]: T;
     }
 }
+
 type Id<T extends _HasId> = string & Tag.OpaqueTag<T>;
+
 type fromId<T> = T extends Id<infer R> ? R : never;
 /**
  * `InterShardMemory` object provides an interface for communicating between shards.
@@ -4057,6 +4059,27 @@ interface RoomTerrain {
      * @return number Number of terrain mask like: TERRAIN_MASK_SWAMP | TERRAIN_MASK_WALL
      */
     get(x: number, y: number): 0 | TERRAIN_MASK_WALL | TERRAIN_MASK_SWAMP;
+    /**
+     * Get copy of underlying static terrain buffer.
+     * @param destinationArray (optional) A typed array view in which terrain will be copied to.
+     * @throws {RangeError} if `destinationArray` is provided, it must have a length of at least 2500 (`50*50`).
+     * @return Copy of underlying room terrain as a new typed array of size 2500.
+     */
+    getRawBuffer<
+        T extends
+            | Int8Array
+            | Uint8Array
+            | Int16Array
+            | Uint16Array
+            | Int32Array
+            | Uint32Array
+            | Uint8ClampedArray
+            | Float32Array
+            | Float64Array,
+    >(
+        destinationArray: T,
+    ): T;
+    getRawBuffer(): Uint8Array;
 }
 
 interface RoomTerrainConstructor extends _Constructor<RoomTerrain> {
diff --git a/dist/screeps-tests.ts b/dist/screeps-tests.ts
index 5f4e92da..15b1a812 100644
--- a/dist/screeps-tests.ts
+++ b/dist/screeps-tests.ts
@@ -1114,6 +1114,10 @@ function resources(o: GenericStore): ResourceConstant[] {
 
     const myTerrain = room.getTerrain();
 
+    const otherTerrain = new Room.Terrain("E2S7");
+
+    const anotherTerrain = Game.map.getRoomTerrain("W2N5");
+
     const ret = myTerrain.get(5, 5);
     if (ret === 0) {
         /*plain*/
@@ -1125,7 +1129,28 @@ function resources(o: GenericStore): ResourceConstant[] {
         /*wall*/
     }
 
-    const enemyTerrain = new Room.Terrain("W2N5");
+    const myRawTerrain = myTerrain.getRawBuffer();
+
+    const otherRawTerrain = otherTerrain.getRawBuffer(new Int8Array(2500));
+
+    const anotherRawTerrain = anotherTerrain.getRawBuffer(new Uint16Array(2500));
+
+    for (const rawTerrain of [myRawTerrain, otherRawTerrain, anotherRawTerrain]) {
+        for (let y = 0; y < 50; y++) {
+            for (let x = 0; x < 50; x++) {
+                const code = rawTerrain[y * 50 + x];
+                if (code === 0) {
+                    /*plain*/
+                }
+                if (code & TERRAIN_MASK_SWAMP) {
+                    /*swamp*/
+                }
+                if (code & TERRAIN_MASK_WALL) {
+                    /*wall*/
+                }
+            }
+        }
+    }
 }
 
 // Creep.body
diff --git a/src/helpers.ts b/src/helpers.ts
index ed93abcb..5461fda7 100644
--- a/src/helpers.ts
+++ b/src/helpers.ts
@@ -433,5 +433,7 @@ declare namespace Tag {
         private [OpaqueTagSymbol]: T;
     }
 }
+
 type Id<T extends _HasId> = string & Tag.OpaqueTag<T>;
+
 type fromId<T> = T extends Id<infer R> ? R : never;
diff --git a/src/room-terrain.ts b/src/room-terrain.ts
index 0ee753e2..bc352116 100644
--- a/src/room-terrain.ts
+++ b/src/room-terrain.ts
@@ -9,6 +9,27 @@ interface RoomTerrain {
      * @return number Number of terrain mask like: TERRAIN_MASK_SWAMP | TERRAIN_MASK_WALL
      */
     get(x: number, y: number): 0 | TERRAIN_MASK_WALL | TERRAIN_MASK_SWAMP;
+    /**
+     * Get copy of underlying static terrain buffer.
+     * @param destinationArray (optional) A typed array view in which terrain will be copied to.
+     * @throws {RangeError} if `destinationArray` is provided, it must have a length of at least 2500 (`50*50`).
+     * @return Copy of underlying room terrain as a new typed array of size 2500.
+     */
+    getRawBuffer<
+        T extends
+            | Int8Array
+            | Uint8Array
+            | Int16Array
+            | Uint16Array
+            | Int32Array
+            | Uint32Array
+            | Uint8ClampedArray
+            | Float32Array
+            | Float64Array,
+    >(
+        destinationArray: T,
+    ): T;
+    getRawBuffer(): Uint8Array;
 }
 
 interface RoomTerrainConstructor extends _Constructor<RoomTerrain> {