Reduce Async FrameBuffer memory usage with PackedWrappedBuffer and static offsets (#90)

- Add PackedWrappedBuffer with pre-shifted slice views (slice2, slice3, slice4) so all BWAPI field offsets remain static compile-time constants with zero runtime branches
- Keep original WrappedBuffer pure, only adding a package-private view constructor
- Auto-generate AsyncClientData and slice-routed struct views (AsyncPosition, AsyncEvent, AsyncCommand, AsyncUnitCommand) via DumpToClient
- Preserve unsafe async handoffs across live and packed buffers for both in-flight reads and retained struct views
- Add unit and synchronization tests covering memory reduction, static/dynamic routing, and unsafe async handoffs

Author: Jasper Geurtz

src/main/java/bwapi/AsyncClientData.java

@@ -29,7 +29,12 @@ class BotWrapperAsync extends BotWrapper {
     void startNewGame(WrappedBuffer liveData, PerformanceMetrics performanceMetrics) {
         frameBuffer.initialize(liveData, performanceMetrics);
 
-        super.startNewGame(liveData, performanceMetrics);
+        this.performanceMetrics = performanceMetrics;
+        AsyncClientData asyncClientData = new AsyncClientData(liveData);
+        botGame = new Game(asyncClientData);
+        botGame.setConfiguration(configuration);
+        botGame.botClientData().setBuffer(liveData);
+        gameOver = false;
 
         liveClientData.setBuffer(liveData);
         this.liveData = liveData;

src/main/java/bwapi/BotWrapperAsync.java

@@ -2,11 +2,14 @@
 
 import com.sun.jna.Pointer;
 
-final class ClientData {
-    private WrappedBuffer buffer;
-    private GameData gameData;
+class ClientData {
+    WrappedBuffer buffer;
+    GameData gameData;
     ClientData() {
-        gameData = new ClientData.GameData(0);
+        gameData = createGameData(0);
+    }
+    GameData createGameData(int offset) {
+        return new ClientData.GameData(offset);
     }
     GameData gameData() {
         return gameData;
@@ -17,9 +20,12 @@ void setBuffer(WrappedBuffer buffer) {
     void setPointer(Pointer pointer) {
         setBuffer(new WrappedBuffer(pointer, GameData.SIZE));
     }
+    WrappedBuffer getStaticBuffer() {
+        return buffer;
+    }
     class UnitCommand {
         static final int SIZE = 24;
-        private int myOffset;
+        protected int myOffset;
         UnitCommand(int myOffset) {
           this.myOffset = myOffset;
         }
@@ -68,7 +74,7 @@ void setExtra(int value) {
     }
     class GameData {
         static final int SIZE = 33017048;
-        private int myOffset;
+        protected int myOffset;
         GameData(int myOffset) {
           this.myOffset = myOffset;
         }
@@ -701,7 +707,7 @@ void setIsSolid(boolean value) {
     }
     class Command {
         static final int SIZE = 12;
-        private int myOffset;
+        protected int myOffset;
         Command(int myOffset) {
           this.myOffset = myOffset;
         }
@@ -729,7 +735,7 @@ void setValue2(int value) {
     }
     class Position {
         static final int SIZE = 8;
-        private int myOffset;
+        protected int myOffset;
         Position(int myOffset) {
           this.myOffset = myOffset;
         }
@@ -750,7 +756,7 @@ void setY(int value) {
     }
     class Event {
         static final int SIZE = 12;
-        private int myOffset;
+        protected int myOffset;
         Event(int myOffset) {
           this.myOffset = myOffset;
         }
@@ -784,94 +790,94 @@ class RegionData {
         }
         int getId() {
             int offset = myOffset + 0;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setId(int value) {
-            buffer.putInt(myOffset + 0, value);
+            getStaticBuffer().putInt(myOffset + 0, value);
         }
         int islandID() {
             int offset = myOffset + 4;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setIslandID(int value) {
-            buffer.putInt(myOffset + 4, value);
+            getStaticBuffer().putInt(myOffset + 4, value);
         }
         int getCenter_x() {
             int offset = myOffset + 8;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setCenter_x(int value) {
-            buffer.putInt(myOffset + 8, value);
+            getStaticBuffer().putInt(myOffset + 8, value);
         }
         int getCenter_y() {
             int offset = myOffset + 12;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setCenter_y(int value) {
-            buffer.putInt(myOffset + 12, value);
+            getStaticBuffer().putInt(myOffset + 12, value);
         }
         int getPriority() {
             int offset = myOffset + 16;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setPriority(int value) {
-            buffer.putInt(myOffset + 16, value);
+            getStaticBuffer().putInt(myOffset + 16, value);
         }
         int getLeftMost() {
             int offset = myOffset + 20;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setLeftMost(int value) {
-            buffer.putInt(myOffset + 20, value);
+            getStaticBuffer().putInt(myOffset + 20, value);
         }
         int getRightMost() {
             int offset = myOffset + 24;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setRightMost(int value) {
-            buffer.putInt(myOffset + 24, value);
+            getStaticBuffer().putInt(myOffset + 24, value);
         }
         int getTopMost() {
             int offset = myOffset + 28;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setTopMost(int value) {
-            buffer.putInt(myOffset + 28, value);
+            getStaticBuffer().putInt(myOffset + 28, value);
         }
         int getBottomMost() {
             int offset = myOffset + 32;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setBottomMost(int value) {
-            buffer.putInt(myOffset + 32, value);
+            getStaticBuffer().putInt(myOffset + 32, value);
         }
         int getNeighborCount() {
             int offset = myOffset + 36;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setNeighborCount(int value) {
-            buffer.putInt(myOffset + 36, value);
+            getStaticBuffer().putInt(myOffset + 36, value);
         }
         int getNeighbors(int i) {
             int offset = myOffset + 40 + 4 * 1 * i;
-            return buffer.getInt(offset);
+            return getStaticBuffer().getInt(offset);
         }
         void setNeighbors(int i, int value) {
-            buffer.putInt(myOffset + 40 + 4 * 1 * i, value);
+            getStaticBuffer().putInt(myOffset + 40 + 4 * 1 * i, value);
         }
         boolean isAccessible() {
             int offset = myOffset + 1064;
-            return buffer.getByte(offset) != 0;
+            return getStaticBuffer().getByte(offset) != 0;
         }
         void setIsAccessible(boolean value) {
-            buffer.putByte(myOffset + 1064, (byte) (value ? 1 : 0));
+            getStaticBuffer().putByte(myOffset + 1064, (byte) (value ? 1 : 0));
         }
         boolean isHigherGround() {
             int offset = myOffset + 1065;
-            return buffer.getByte(offset) != 0;
+            return getStaticBuffer().getByte(offset) != 0;
         }
         void setIsHigherGround(boolean value) {
-            buffer.putByte(myOffset + 1065, (byte) (value ? 1 : 0));
+            getStaticBuffer().putByte(myOffset + 1065, (byte) (value ? 1 : 0));
         }
     }
     class ForceData {
@@ -2002,4 +2008,3 @@ void setReplayID(int value) {
         }
     }
 }
-

src/main/java/bwapi/ClientData.java

@@ -11,7 +11,7 @@
  * Circular buffer of game states.
  */
 class FrameBuffer {
-    private static final int BUFFER_SIZE = ClientData.GameData.SIZE;
+    static final int BUFFER_SIZE = PackedWrappedBuffer.BUFFER_SIZE;
     private static final Unsafe unsafe = UnsafeTools.getUnsafe();
 
     private WrappedBuffer liveData;
@@ -30,7 +30,7 @@ class FrameBuffer {
         this.capacity = configuration.getAsyncFrameBufferCapacity();
         this.configuration = configuration;
         while(dataBuffer.size() < capacity) {
-            dataBuffer.add(new WrappedBuffer(BUFFER_SIZE));
+            dataBuffer.add(new PackedWrappedBuffer());
         }
     }
 
@@ -107,17 +107,15 @@ void enqueueFrame() {
                 performanceMetrics.getIntentionallyBlocking().stopTiming();
             } finally { lockSize.unlock(); };
 
-            // For the first frame of the game, populate all buffers completely
-            // This is to ensure all buffers have access to immutable data like regions/walkability/buildability
-            // Afterwards, we want to shorten this process by only copying important and mutable data
+            // Copy dynamic game information into the current frame buffer slot.
+            // Static information (e.g. walkability/buildability/regions) is accessed
+            // directly from the main shared memory buffer by AsyncClientData.
             if (stepGame == 0) {
-                for (WrappedBuffer frameBuffer : dataBuffer) {
-                    copyBuffer(liveData, frameBuffer, true);
-                }
+                copyBuffer(liveData, dataBuffer.get(indexGame()));
             } else {
                 performanceMetrics.getCopyingToBuffer().time(() -> {
                     WrappedBuffer dataTarget = dataBuffer.get(indexGame());
-                    copyBuffer(liveData, dataTarget, false);
+                    copyBuffer(liveData, dataTarget);
                 });
             }
 
@@ -153,45 +151,10 @@ void dequeue() {
         } finally { lockSize.unlock(); }
     }
 
-    /**
-     *
-     * @param source Address to copy from
-     * @param destination Address to copy to
-     * @param size Number of bytes to copy
-     */
-    private void copyBuffer(WrappedBuffer source, WrappedBuffer destination, long offset, int size) {
-        long addressSource = source.getAddress() + offset;
-        long addressDestination = destination.getAddress() + offset;
-        unsafe.copyMemory(addressSource, addressDestination, size);
-    }
-
-    void copyBuffer(WrappedBuffer source, WrappedBuffer destination, boolean copyEverything) {
-        /*
-        The speed at which we copy data into the frame buffer is a major cost of JBWAPI's asynchronous operation.
-        Copy times observed in the wild for the complete buffer usually range from 2.6ms - 19ms
-        but are prone to large amounts of variance.
-
-        The normal Java way to execute this copy is via ByteBuffer.put(), which has reasonably good performance characteristics.
-        */
-
-        if (copyEverything) {
-            copyBuffer(source, destination, 0, FrameBuffer.BUFFER_SIZE);
-        } else {
-            // After the buffer has been filled the first time,
-            // we can omit copying blocks of data which are unused or which don't change after game start.
-            // These blocks account for *most* of the 33MB shared memory,
-            // so omitting them drastically reduces the copy duration
-            final int STATICTILES_START = 3447004; // getGroundHeight, isWalkable, isBuildable
-            final int STATICTILES_END = 4823260;
-            final int REGION_START = 5085404; // getMapTileRegionId, ..., getRegions
-            final int REGION_END = 10586480;
-            final int STRINGSSHAPES_START = 10962632; // getStringCount, ... getShapes
-            final int STRINGSHAPES_END = 32242636;
-            final int UNITFINDER_START = 32962644;
-            copyBuffer(source, destination, 0, STATICTILES_START);
-            copyBuffer(source, destination, STATICTILES_END, REGION_START - STATICTILES_END);
-            copyBuffer(source, destination, REGION_END, STRINGSSHAPES_START - REGION_END);
-            copyBuffer(source, destination, STRINGSHAPES_END, UNITFINDER_START - STRINGSHAPES_END);
-        }
+    void copyBuffer(WrappedBuffer source, WrappedBuffer destination) {
+        unsafe.copyMemory(source.getAddress() + 0, destination.getAddress() + PackedWrappedBuffer.DEST_SLICE1_OFFSET, PackedWrappedBuffer.DYNAMIC_SLICE1_SIZE);
+        unsafe.copyMemory(source.getAddress() + PackedWrappedBuffer.STATICTILES_END, destination.getAddress() + PackedWrappedBuffer.DEST_SLICE2_OFFSET, PackedWrappedBuffer.DYNAMIC_SLICE2_SIZE);
+        unsafe.copyMemory(source.getAddress() + PackedWrappedBuffer.REGION_END, destination.getAddress() + PackedWrappedBuffer.DEST_SLICE3_OFFSET, PackedWrappedBuffer.DYNAMIC_SLICE3_SIZE);
+        unsafe.copyMemory(source.getAddress() + PackedWrappedBuffer.STRINGSHAPES_END, destination.getAddress() + PackedWrappedBuffer.DEST_SLICE4_OFFSET, PackedWrappedBuffer.DYNAMIC_SLICE4_SIZE);
     }
 }

src/main/java/bwapi/FrameBuffer.java

@@ -106,7 +106,11 @@ public final class Game {
     final SideEffectQueue sideEffects = new SideEffectQueue();
 
     Game() {
-        clientData = new ClientData();
+        this(new ClientData());
+    }
+
+    Game(ClientData clientData) {
+        this.clientData = clientData;
     }
 
     void setConfiguration(BWClientConfiguration configuration) {

src/main/java/bwapi/Game.java

@@ -0,0 +1,54 @@
+package bwapi;
+
+/**
+ * Packed off-heap buffer for asynchronous frame slots that stores only dynamic game data slices
+ * and exposes pre-shifted slice views so static BWAPI offsets work without runtime branching.
+ */
+class PackedWrappedBuffer extends WrappedBuffer {
+    static final int STATICTILES_START = 3447004;
+    static final int STATICTILES_END = 4823260;
+    static final int REGION_START = 5085404;
+    static final int REGION_END = 10586480;
+    static final int STRINGSSHAPES_START = 10962632;
+    static final int STRINGSHAPES_END = 32242636;
+    static final int UNITFINDER_START = 32962644;
+
+    static final int DYNAMIC_SLICE1_SIZE = STATICTILES_START;
+    static final int DYNAMIC_SLICE2_SIZE = REGION_START - STATICTILES_END;
+    static final int DYNAMIC_SLICE3_SIZE = STRINGSSHAPES_START - REGION_END;
+    static final int DYNAMIC_SLICE4_SIZE = UNITFINDER_START - STRINGSHAPES_END;
+
+    static final int DEST_SLICE1_OFFSET = 0;
+    static final int DEST_SLICE2_OFFSET = DYNAMIC_SLICE1_SIZE;
+    static final int DEST_SLICE3_OFFSET = DEST_SLICE2_OFFSET + DYNAMIC_SLICE2_SIZE;
+    static final int DEST_SLICE4_OFFSET = DEST_SLICE3_OFFSET + DYNAMIC_SLICE3_SIZE;
+
+    static final int BUFFER_SIZE = DEST_SLICE4_OFFSET + DYNAMIC_SLICE4_SIZE;
+
+    static final int DELTA_RANGE2 = STATICTILES_END - STATICTILES_START;
+    static final int DELTA_RANGE3 = DELTA_RANGE2 + (REGION_END - REGION_START);
+    static final int DELTA_RANGE4 = DELTA_RANGE3 + (STRINGSHAPES_END - STRINGSSHAPES_START);
+
+    final WrappedBuffer slice2;
+    final WrappedBuffer slice3;
+    final WrappedBuffer slice4;
+
+    PackedWrappedBuffer() {
+        this(BUFFER_SIZE);
+    }
+
+    PackedWrappedBuffer(final int size) {
+        super(size);
+        long addr = getAddress();
+        this.slice2 = new WrappedBuffer(getBuffer(), addr - DELTA_RANGE2);
+        this.slice3 = new WrappedBuffer(getBuffer(), addr - DELTA_RANGE3);
+        this.slice4 = new WrappedBuffer(getBuffer(), addr - DELTA_RANGE4);
+    }
+
+    PackedWrappedBuffer(final WrappedBuffer unpacked) {
+        super(null, 0L);
+        this.slice2 = unpacked;
+        this.slice3 = unpacked;
+        this.slice4 = unpacked;
+    }
+}

src/main/java/bwapi/PackedWrappedBuffer.java

@@ -24,6 +24,11 @@ class WrappedBuffer {
         this.address = Pointer.nativeValue(pointer);
     }
 
+    WrappedBuffer(final ByteBuffer buffer, final long address) {
+        this.buffer = buffer;
+        this.address = address;
+    }
+
     byte getByte(final int offset) {
         return unsafe.getByte(address + offset);
     }