Only copy active units, events, and eventStrings in FrameBuffer

Author: Jasper Geurtz

src/main/java/bwapi/FrameBuffer.java

@@ -12,6 +12,21 @@
  */
 class FrameBuffer {
     static final int BUFFER_SIZE = PackedWrappedBuffer.BUFFER_SIZE;
+
+    static final int INITIAL_UNIT_COUNT_OFFSET = 69648;
+    static final int UNITS_START = 69656;
+    static final int MAX_UNITS = 10000;
+    static final int UNITS_END = UNITS_START + MAX_UNITS * ClientData.UnitData.SIZE;
+
+    static final int EVENT_COUNT_OFFSET = 10586620;
+    static final int EVENTS_START = 10586624;
+    static final int MAX_EVENTS = 10000;
+    static final int EVENTS_HEADER_SIZE = EVENTS_START - PackedWrappedBuffer.REGION_END;
+
+    static final int EVENT_STRING_COUNT_OFFSET = 10706624;
+    static final int EVENT_STRING_SIZE = 256;
+    static final int MAX_EVENT_STRINGS = 1000;
+
     private static final Unsafe unsafe = UnsafeTools.getUnsafe();
 
     private WrappedBuffer liveData;
@@ -20,6 +35,7 @@ class FrameBuffer {
     private final int capacity;
     private int stepGame = 0;
     private int stepBot = 0;
+    private int maxUnitCount = 0;
     private final ArrayList<WrappedBuffer> dataBuffer = new ArrayList<>();
 
     private final Lock lockWrite = new ReentrantLock();
@@ -42,6 +58,7 @@ void initialize(WrappedBuffer liveData, PerformanceMetrics performanceMetrics) {
         this.performanceMetrics = performanceMetrics;
         stepGame = 0;
         stepBot = 0;
+        maxUnitCount = 0;
     }
 
     /**
@@ -151,9 +168,88 @@ void dequeue() {
         } finally { lockSize.unlock(); }
     }
 
+    /**
+     * 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 33 MB shared memory buffer used to range from 2.6ms - 19ms
+     * and are prone to large amounts of variance.
+     *
+     * To minimize both memory footprint and copy time, we:
+     * 1. Omit static map and region data (groundHeight, isWalkable, isBuildable, regions), which are read directly
+     *    from the main shared memory buffer via AsyncClientData.
+     * 2. Omit client-to-server output buffers (strings, shapes, commands, unitCommands), which are flushed directly
+     *    to live shared memory by SideEffectQueue at the end of the frame.
+     * 3. Pack the remaining 3 dynamic ranges into a 4.08 MB PackedWrappedBuffer (using pre-shifted slice views so
+     *    static BWAPI field offsets work without runtime branching).
+     * 4. Within those ranges, only copy the currently active prefixes of units[0..maxUnitCount),
+     *    events[0..eventCount), and eventStrings[0..eventStringCount), skipping their unused tails.
+     *
+     * Approximate bytes copied per frame (Fastest game speed ~= 23.8 frames/sec, ~1,428 frames/minute):
+     * - Fixed base (header, forces, players, bullets, dynamic tile flags): ~349 KB (0.35 MB)
+     * - Game start (Frame 0, ~300 initial units):                          ~450 KB (0.45 MB)
+     * - Mid-game   (~8-10 min / ~7,500 frames, ~1,000 cumulative units):   ~685 KB (0.69 MB)
+     * - Late-game  (~20+ min / ~20,000 frames, ~2,500 cumulative units):   ~1.19 MB (max cap at 10,000 units: 4.08 MB)
+     *
+     * Estimated per-frame copy times across hardware and CPU core counts:
+     * +-----------------------------------------------+---------------+---------------+---------------+---------------+
+     * | Environment / Hardware & Core Count           | Start (450KB) | Mid (685KB)   | Late (1.19MB) | Max (4.08MB)  |
+     * +-----------------------------------------------+---------------+---------------+---------------+---------------+
+     * | Weak / Virtualized (1-vCPU Docker / shared VM | 0.12 - 0.35ms | 0.18 - 0.50ms | 0.30 - 0.85ms | 1.00 - 2.80ms |
+     * | ~3-5 GB/s; Wine, Client & Bot share 1 core)   |               |               |               |               |
+     * +-----------------------------------------------+---------------+---------------+---------------+---------------+
+     * | Normal Desktop / Tourney VM (2-4 cores, DDR4, | 0.04 - 0.08ms | 0.06 - 0.12ms | 0.10 - 0.20ms | 0.30 - 0.60ms |
+     * | ~12 GB/s; Copy runs in parallel with Bot)     |               |               |               |               |
+     * +-----------------------------------------------+---------------+---------------+---------------+---------------+
+     * | Fast Modern CPU (4+ cores, DDR5, ~30+ GB/s;   | 0.01 - 0.03ms | 0.02 - 0.05ms | 0.04 - 0.08ms | 0.12 - 0.25ms |
+     * | fits in L2/L3, finishes before Bot wakes)     |               |               |               |               |
+     * +-----------------------------------------------+---------------+---------------+---------------+---------------+
+     */
     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);
+        long srcAddr = source.getAddress();
+        long dstAddr = destination.getAddress();
+
+        int eventCount = clamp(source.getInt(EVENT_COUNT_OFFSET), 0, MAX_EVENTS);
+        int eventStringCount = clamp(source.getInt(EVENT_STRING_COUNT_OFFSET), 0, MAX_EVENT_STRINGS);
+        int activeUnits = updateMaxUnitCount(source, eventCount);
+
+        // Slice 1a (dynamic size): header, forces, players, initialUnitCount, and active units [0 .. activeUnits)
+        copySlice(srcAddr, dstAddr, 0, 0, UNITS_START + activeUnits * ClientData.UnitData.SIZE);
+        // Slice 1b (static size): unitArray, bullets, nukeDots, frameCount, and other post-unit Slice 1 fields
+        copySlice(srcAddr, dstAddr, UNITS_END, 0, PackedWrappedBuffer.STATICTILES_START - UNITS_END);
+        // Slice 2 (static size): tile visibility, exploration, creep, and occupation flags
+        copySlice(srcAddr, dstAddr, PackedWrappedBuffer.STATICTILES_END, PackedWrappedBuffer.DELTA_RANGE2, PackedWrappedBuffer.DYNAMIC_SLICE2_SIZE);
+        // Slice 3a (dynamic size): startLocations, game state flags, selectedUnits, self/enemy/neutral, eventCount, and active events [0 .. eventCount)
+        copySlice(srcAddr, dstAddr, PackedWrappedBuffer.REGION_END, PackedWrappedBuffer.DELTA_RANGE3, EVENTS_HEADER_SIZE + eventCount * ClientData.Event.SIZE);
+        // Slice 3b (dynamic size): eventStringCount and active eventStrings [0 .. eventStringCount)
+        copySlice(srcAddr, dstAddr, EVENT_STRING_COUNT_OFFSET, PackedWrappedBuffer.DELTA_RANGE3, 4 + eventStringCount * EVENT_STRING_SIZE);
+    }
+
+    int getMaxUnitCount() {
+        return maxUnitCount;
+    }
+
+    private static int clamp(int value, int min, int max) {
+        return Math.max(min, Math.min(max, value));
+    }
+
+    private int updateMaxUnitCount(WrappedBuffer source, int eventCount) {
+        int initialUnits = clamp(source.getInt(INITIAL_UNIT_COUNT_OFFSET), 0, MAX_UNITS);
+        if (initialUnits > maxUnitCount) {
+            maxUnitCount = initialUnits;
+        }
+
+        for (int i = 0; i < eventCount; i++) {
+            int eventOffset = EVENTS_START + i * ClientData.Event.SIZE;
+            if (source.getInt(eventOffset) == EventType.UnitDiscover.id) {
+                int unitId = source.getInt(eventOffset + 4);
+                if (unitId >= 0 && unitId < MAX_UNITS && unitId + 1 > maxUnitCount) {
+                    maxUnitCount = unitId + 1;
+                }
+            }
+        }
+        return maxUnitCount;
+    }
+
+    private static void copySlice(long srcAddr, long dstAddr, int srcOffset, int delta, int length) {
+        unsafe.copyMemory(srcAddr + srcOffset, dstAddr + srcOffset - delta, length);
     }
 }

src/test/java/bwapi/AsyncClientDataTest.java

@@ -12,6 +12,7 @@ public void retainedViewsSurviveLiveAndPackedHandoffs() {
         PackedWrappedBuffer packed = new PackedWrappedBuffer(ClientData.GameData.SIZE);
         ClientData source = new ClientData();
         source.setBuffer(live);
+        source.gameData().setEventCount(1);
         source.gameData().getEvents(0).setType(EventType.MatchFrame);
         source.gameData().getStartLocations(0).setX(123);
         new FrameBuffer(new BWClientConfiguration.Builder().withAsyncFrameBufferCapacity(1).build())
@@ -213,4 +214,46 @@ public void asyncClientDataWorksWithFullUnpackedBuffer() {
         assertTrue(asyncData.gameData().isVisible(10, 20));
         assertTrue(asyncData.gameData().isInGame());
     }
+
+    @Test
+    public void copyBufferTracksMaxUnitsAndOnlyCopiesActiveUnitsAndEvents() {
+        WrappedBuffer mainBuffer = new WrappedBuffer(ClientData.GameData.SIZE);
+        PackedWrappedBuffer packedBuffer = new PackedWrappedBuffer();
+
+        ClientData mainData = new ClientData();
+        mainData.setBuffer(mainBuffer);
+
+        // Set initialUnitCount = 3 and populate unit #2 and unit #50 (beyond initialUnitCount)
+        mainData.gameData().setInitialUnitCount(3);
+        mainData.gameData().getUnits(2).setHitPoints(100);
+        mainData.gameData().getUnits(50).setHitPoints(250);
+
+        // Populate event #0 (active) and event #5 (beyond eventCount = 1)
+        mainData.gameData().setEventCount(1);
+        mainData.gameData().getEvents(0).setType(EventType.MatchFrame);
+        mainData.gameData().getEvents(5).setType(EventType.MatchEnd);
+
+        FrameBuffer frameBuffer = new FrameBuffer(
+                new BWClientConfiguration.Builder().withAsyncFrameBufferCapacity(1).build());
+        frameBuffer.copyBuffer(mainBuffer, packedBuffer);
+
+        AsyncClientData asyncData = new AsyncClientData(mainBuffer);
+        asyncData.setBuffer(packedBuffer);
+
+        assertEquals(3, frameBuffer.getMaxUnitCount());
+        assertEquals(100, asyncData.gameData().getUnits(2).getHitPoints());
+        // Unit #50 and Event #5 were beyond active counts, so they were skipped
+        assertEquals(0, asyncData.gameData().getUnits(50).getHitPoints());
+        assertEquals(EventType.MatchFrame, asyncData.gameData().getEvents(0).getType());
+        assertEquals(EventType.MatchStart, asyncData.gameData().getEvents(5).getType());
+
+        // Now fire UnitDiscover for unit #50 on the next frame
+        mainData.gameData().setEventCount(1);
+        mainData.gameData().getEvents(0).setType(EventType.UnitDiscover);
+        mainData.gameData().getEvents(0).setV1(50);
+        frameBuffer.copyBuffer(mainBuffer, packedBuffer);
+
+        assertEquals(51, frameBuffer.getMaxUnitCount());
+        assertEquals(250, asyncData.gameData().getUnits(50).getHitPoints());
+    }
 }