Asynchronous mode

pom.xml

@@ -61,8 +61,10 @@
  <artifactId>maven-surefire-plugin</artifactId>
  <version>2.22.2</version>
  <configuration>
- <parallel>all</parallel> <!-- Run tests in parallel-->
- <useUnlimitedThreads>true</useUnlimitedThreads>
+<!-- <parallel>all</parallel> &lt;!&ndash; Run tests in parallel&ndash;&gt;-->
+<!-- <useUnlimitedThreads>true</useUnlimitedThreads>-->
+ <rerunFailingTestsCount>10</rerunFailingTestsCount>
+ <argLine>-Xms1g -Xmx1g</argLine>
  </configuration>
  </plugin>
  <plugin>

src/main/java/bwapi/BWClient.java

@@ -1,64 +1,142 @@
 package bwapi;
 
+import com.sun.jna.platform.win32.Kernel32;
+
 import java.util.Objects;
 
 /**
  * Client class to connect to the game with.
  */
 public class BWClient {
+ private BWClientConfiguration configuration = new BWClientConfiguration();
  private final BWEventListener eventListener;
- private final boolean debugConnection;
- private EventHandler handler;
+ private BotWrapper botWrapper;
+ private Client client;
+ private PerformanceMetrics performanceMetrics;
 
  public BWClient(final BWEventListener eventListener) {
- this(eventListener, false);
- }
-
- /**
- * @param debugConnection set to `true` for more explicit error messages (might spam the terminal).
- * `false` by default
- */
- public BWClient(final BWEventListener eventListener, final boolean debugConnection) {
  Objects.requireNonNull(eventListener);
- this.debugConnection = debugConnection;
  this.eventListener = eventListener;
  }
 
  /**
  * Get the {@link Game} instance of the currently running game.
+ * When running in asynchronous mode, this is the game from the bot's perspective, eg. potentially a previous frame.
  */
  public Game getGame() {
- return handler == null ? null : handler.getGame();
+ return botWrapper == null ? null : botWrapper.getGame();
+ }
+
+ /**
+ * @return JBWAPI performance metrics.
+ */
+ public PerformanceMetrics getPerformanceMetrics() {
+ return performanceMetrics;
+ }
+
+ /**
+ * @return The current configuration
+ */
+ public BWClientConfiguration getConfiguration() {
+ return configuration;
+ }
+
+ /**
+ * @return Whether the current frame should be subject to timing.
+ */
+ boolean doTime() {
+ return ! configuration.getUnlimitedFrameZero() || (client.isConnected() && client.liveClientData().gameData().getFrameCount() > 0);
+ }
+
+ /**
+ * @return The number of frames between the one exposed to the bot and the most recent received by JBWAPI.
+ * This tracks the size of the frame buffer except when the game is paused (which results in multiple frames arriving with the same count).
+ */
+ public int framesBehind() {
+ return botWrapper == null ? 0 : Math.max(0, client.liveClientData().gameData().getFrameCount() - getGame().getFrameCount());
  }
 
+ /**
+ * For internal test use.
+ */
+ Client getClient() {
+ return client;
+ }
+
+ /**
+ * Start the game with default settings.
+ */
  public void startGame() {
- startGame(false);
+ BWClientConfiguration configuration = new BWClientConfiguration();
+ startGame(configuration);
  }
 
  /**
  * Start the game.
  *
  * @param autoContinue automatically continue playing the next game(s). false by default
  */
+ @Deprecated
  public void startGame(boolean autoContinue) {
- Client client = new Client(debugConnection);
+ BWClientConfiguration configuration = new BWClientConfiguration();
+ configuration.withAutoContinue(autoContinue);
+ startGame(configuration);
+ }
+
+ /**
+ * Start the game.
+ *
+ * @param gameConfiguration Settings for playing games with this client.
+ */
+ public void startGame(BWClientConfiguration gameConfiguration) {
+ gameConfiguration.validateAndLock();
+ this.configuration = gameConfiguration;
+ this.performanceMetrics = new PerformanceMetrics(configuration);
+ botWrapper = new BotWrapper(configuration, eventListener);
+
+ // Use reduced priority to encourage Windows to give priority to StarCraft.exe/BWAPI.
+ // If BWAPI doesn't get priority, it may not detect completion of a frame on our end in timely fashion.
+ Thread.currentThread().setName("JBWAPI Client");
+ if (configuration.getAsync()) {
+ Thread.currentThread().setPriority(4);
+ }
+
+ if (client == null) {
+ client = new Client(this);
+ }
  client.reconnect();
- handler = new EventHandler(eventListener, client);
 
  do {
- while (!getGame().isInGame()) {
+ ClientData.GameData liveGameData = client.liveClientData().gameData();
+ while (!liveGameData.isInGame()) {
  if (!client.isConnected()) {
  return;
  }
- client.update(handler);
+ client.sendFrameReceiveFrame();
+ if (liveGameData.isInGame()) {
+ performanceMetrics = new PerformanceMetrics(configuration);
+ botWrapper.startNewGame(client.mapFile(), performanceMetrics);
+ }
  }
- while (getGame().isInGame()) {
- client.update(handler);
+ while (liveGameData.isInGame()) {
+ botWrapper.onFrame();
+ performanceMetrics.getFlushSideEffects().time(() -> getGame().sideEffects.flushTo(liveGameData));
+ performanceMetrics.getFrameDurationReceiveToSend().stopTiming();
+
+ client.sendFrameReceiveFrame();
  if (!client.isConnected()) {
  System.out.println("Reconnecting...");
  client.reconnect();
  }
  }
- } while (autoContinue); // lgtm [java/constant-loop-condition]
+ botWrapper.endGame();
+ } while (configuration.getAutoContinue());
+ }
+
+ /**
+ * Provides a Client. Intended for test consumers only.
+ */
+ void setClient(Client client) {
+ this.client = client;
  }
 }

src/main/java/bwapi/BWClientConfiguration.java

@@ -0,0 +1,163 @@
+package bwapi;
+
+/**
+ * Configuration for constructing a BWClient
+ */
+public class BWClientConfiguration {
+
+ /**
+ * Set to `true` for more explicit error messages (which might spam the terminal).
+ */
+ public BWClientConfiguration withDebugConnection(boolean value) {
+ throwIfLocked();
+ debugConnection = value;
+ return this;
+ }
+ public boolean getDebugConnection() {
+ return debugConnection;
+ }
+ private boolean debugConnection;
+
+ /**
+ * When true, restarts the client loop when a game ends, allowing the client to play multiple games without restarting.
+ */
+ public BWClientConfiguration withAutoContinue(boolean value) {
+ throwIfLocked();
+ autoContinue = value;
+ return this;
+ }
+ public boolean getAutoContinue() {
+ return autoContinue;
+ }
+ private boolean autoContinue = false;
+
+ /**
+ * Most bot tournaments allow bots to take an indefinite amount of time on frame #0 (the first frame of the game) to analyze the map and load data,
+ * as the bot has no prior access to BWAPI or game information.
+ *
+ * This flag indicates that taking arbitrarily long on frame zero is acceptable.
+ * Performance metrics omit the frame as an outlier.
+ * Asynchronous operation will block until the bot's event handlers are complete.
+ */
+ public BWClientConfiguration withUnlimitedFrameZero(boolean value) {
+ throwIfLocked();
+ unlimitedFrameZero = value;
+ return this;
+ }
+ public boolean getUnlimitedFrameZero() {
+ return unlimitedFrameZero;
+ }
+ private boolean unlimitedFrameZero = true;
+
+ /**
+ * The maximum amount of time the bot is supposed to spend on a single frame.
+ * In asynchronous mode, JBWAPI will attempt to let the bot use up to this much time to process all frames before returning control to BWAPI.
+ * In synchronous mode, JBWAPI is not empowered to prevent the bot to exceed this amount, but will record overruns in performance metrics.
+ * Real-time human play typically uses the "fastest" game speed, which has 42.86ms (42,860ns) between frames.
+ */
+ public BWClientConfiguration withMaxFrameDurationMs(int value) {
+ throwIfLocked();
+ maxFrameDurationMs = value;
+ return this;
+ }
+ public int getMaxFrameDurationMs() {
+ return maxFrameDurationMs;
+ }
+ private int maxFrameDurationMs = 40;
+
+ /**
+ * Runs the bot in asynchronous mode. Asynchronous mode helps attempt to ensure that the bot adheres to real-time performance constraints.
+ *
+ * Humans playing StarCraft (and some tournaments) expect bots to return commands within a certain period of time; ~42ms for humans ("fastesT" game speed),
+ * and some tournaments enforce frame-wise time limits (at time of writing, 55ms for COG and AIIDE; 85ms for SSCAIT).
+ *
+ * Asynchronous mode invokes bot event handlers in a separate thread, and if all event handlers haven't returned by a specified period of time, sends an
+ * returns control to StarCraft, allowing the game to proceed while the bot continues to step in the background. This increases the likelihood of meeting
+ * real-time performance requirements, while not fully guaranteeing it (subject to the whims of the JVM thread scheduler), at a cost of the bot possibly
+ * issuing commands later than intended, and a marginally larger memory footprint.
+ *
+ * Asynchronous mode is not compatible with latency compensation. Enabling asynchronous mode automatically disables latency compensation.
+ */
+ public BWClientConfiguration withAsync(boolean value) {
+ throwIfLocked();
+ async = value;
+ return this;
+ }
+ public boolean getAsync() {
+ return async;
+ }
+ private boolean async = false;
+
+ /**
+ * The maximum number of frames to buffer while waiting on a bot.
+ * Each frame buffered adds about 33 megabytes to JBWAPI's memory footprint.
+ */
+ public BWClientConfiguration withAsyncFrameBufferCapacity(int size) {
+ throwIfLocked();
+ asyncFrameBufferCapacity = size;
+ return this;
+ }
+ public int getAsyncFrameBufferCapacity() {
+ return asyncFrameBufferCapacity;
+ }
+ private int asyncFrameBufferCapacity = 10;
+
+ /**
+ * Enables thread-unsafe async mode.
+ * In this mode, the bot is allowed to read directly from shared memory until shared memory has been copied into the frame buffer,
+ * at wihch point the bot switches to using the frame buffer.
+ * This should enhance performance by allowing the bot to act while the frame is copied, but poses unidentified risk due to
+ * the non-thread-safe switc from shared memory reads to frame buffer reads.
+ */
+ public BWClientConfiguration withAsyncUnsafe(boolean value) {
+ throwIfLocked();
+ asyncUnsafe = value;
+ return this;
+ }
+ public boolean getAsyncUnsafe() {
+ return asyncUnsafe;
+ }
+ private boolean asyncUnsafe = false;
+
+ /**
+ * Toggles verbose logging, particularly of synchronization steps.
+ */
+ public BWClientConfiguration withLogVerbosely(boolean value) {
+ throwIfLocked();
+ logVerbosely = value;
+ return this;
+ }
+ public boolean getLogVerbosely() {
+ return logVerbosely;
+ }
+ private boolean logVerbosely = false;
+
+ /**
+ * Checks that the configuration is in a valid state. Throws an IllegalArgumentException if it isn't.
+ */
+ void validateAndLock() {
+ if (asyncUnsafe && ! async) {
+ throw new IllegalArgumentException("asyncUnsafe mode needs async mode.");
+ }
+ if (async && maxFrameDurationMs < 0) {
+ throw new IllegalArgumentException("maxFrameDurationMs needs to be a non-negative number (it's how long JBWAPI waits for a bot response before returning control to BWAPI).");
+ }
+ if (async && asyncFrameBufferCapacity < 1) {
+ throw new IllegalArgumentException("asyncFrameBufferCapacity needs to be a positive number (There needs to be at least one frame buffer).");
+ }
+ locked = true;
+ }
+ private boolean locked = false;
+
+ void throwIfLocked() {
+ if (locked) {
+ throw new RuntimeException("Configuration can not be modified after the game has started");
+ }
+ }
+
+ void log(String value) {
+ if (logVerbosely) {
+ System.out.println(value);
+ }
+ }
+}