Added client configuration object to replace individual constructor arguments.

Author: dgant

src/main/java/bwapi/BWClient.java

@@ -7,20 +7,10 @@
  */
 public class BWClient {
     private final BWEventListener eventListener;
-    private final boolean debugConnection;
     private EventHandler handler;
 
     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;
     }
 
@@ -32,16 +22,29 @@ public Game getGame() {
     }
 
     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.autoContinue = autoContinue;
+        startGame(configuration);
+    }
+
+    /**
+     * Start the game.
+     *
+     * @param configuration Settings for playing games with this client.
+     */
+    public void startGame(BWClientConfiguration configuration) {
+        Client client = new Client(configuration);
         client.reconnect();
         handler = new EventHandler(eventListener, client);
 
@@ -59,6 +62,6 @@ public void startGame(boolean autoContinue) {
                     client.reconnect();
                 }
             }
-        } while (autoContinue); // lgtm [java/constant-loop-condition]
+        } while (configuration.autoContinue); // lgtm [java/constant-loop-condition]
     }
 }

src/main/java/bwapi/BWClientConfiguration.java

@@ -0,0 +1,55 @@
+package bwapi;
+
+/**
+ * Configuration for constructing a BWClient
+ */
+public class BWClientConfiguration {
+
+    /**
+     * When true, restarts the client loop when a game ends, allowing the client to play multiple games without restarting.
+     */
+    public boolean autoContinue = false;
+
+    /**
+     * 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 run 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.
+     */
+    public boolean async = false;
+
+    /**
+     * If JBWAPI detects that this much time (in nanoseconds) has passed since a bot's event handlers began, returns control back to BWAPI.
+     * Real-time human play typically uses the "fastest" game speed, which has 42.86ms (42,860ns) between frames.
+     */
+    public int asyncFrameDurationNanosMax = 40000;
+
+    /**
+     * How frequently (in nanoseconds) to poll for the bot's event handlers completing. Acts as a floor on the bot's frame duration.
+     */
+    public int asyncFrameDurationNanosMin = 500;
+
+    /**
+     * The maximum number of frames to buffer while waiting on a bot
+     */
+    public int asyncFrameBufferSize = 10;
+
+    /**
+     * 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 causes JBWAPI to wait for the bot's event handlers to return on the first frame of the game, even if operating in asynchronous mode,
+     * respecting the time bots are typically allowed on frame 0.
+     */
+    public boolean asyncWaitOnFrameZero = true;
+
+    /**
+     * Set to `true` for more explicit error messages (which might spam the terminal).
+     */
+    public boolean debugConnection;
+}

src/main/java/bwapi/Client.java

@@ -60,10 +60,10 @@ public interface EventHandler {
     private ByteBuffer mapFileHandle = null;
     private ByteBuffer gameTableFileHandle = null;
 
-    private boolean debugConnection = false;
+    private BWClientConfiguration configuration = new BWClientConfiguration();
 
-    Client(boolean debugConnection) {
-        this.debugConnection = debugConnection;
+    Client(BWClientConfiguration configuration) {
+        this.configuration = configuration;
     }
 
     /**
@@ -93,7 +93,7 @@ void reconnect(){
     }
 
     void disconnect() {
-        if (debugConnection) {
+        if (configuration.debugConnection) {
             System.err.print("Disconnect called by: ");
             System.err.println(Thread.currentThread().getStackTrace()[2]);
         }
@@ -143,7 +143,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to map Game table.");
-            if (debugConnection) {
+            if (configuration.debugConnection) {
                 e.printStackTrace();
             }
             return false;
@@ -177,7 +177,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to open communications pipe: " + communicationPipe);
-            if (debugConnection) {
+            if (configuration.debugConnection) {
                 e.printStackTrace();
             }
             gameTableFileHandle = null;
@@ -192,7 +192,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to open shared memory mapping: " + sharedMemoryName);
-            if (debugConnection) {
+            if (configuration.debugConnection) {
                 e.printStackTrace();
             }
             pipeObjectHandle = null;
@@ -205,7 +205,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to map game data.");
-            if (debugConnection) {
+            if (configuration.debugConnection) {
                 e.printStackTrace();
             }
             return false;
@@ -226,7 +226,7 @@ boolean connect() {
             }
             catch (Exception e) {
                 System.err.println("Unable to read pipe object.");
-                if (debugConnection) {
+                if (configuration.debugConnection) {
                     e.printStackTrace();
                 }
                 disconnect();
@@ -246,7 +246,7 @@ void update(final EventHandler handler) {
         }
         catch (Exception e) {
             System.err.println("failed, disconnecting");
-            if (debugConnection) {
+            if (configuration.debugConnection) {
                 e.printStackTrace();
             }
             disconnect();
@@ -258,7 +258,7 @@ void update(final EventHandler handler) {
             }
             catch (Exception e) {
                 System.err.println("failed, disconnecting");
-                if (debugConnection) {
+                if (configuration.debugConnection) {
                     e.printStackTrace();
                 }
                 disconnect();