bwapi

Class BWClientConfiguration

java.lang.Object

bwapi.BWClientConfiguration

public class BWClientConfiguration
extends Object

Configuration for constructing a BWClient

Constructor Summary

Constructors

Constructor and Description
BWClientConfiguration()

Method Summary

Modifier and Type	Method and Description
boolean	getAsync()
int	getAsyncFrameBufferCapacity()
boolean	getAsyncUnsafe()
boolean	getAutoContinue()
boolean	getDebugConnection()
boolean	getLogVerbosely()
int	getMaxFrameDurationMs()
boolean	getUnlimitedFrameZero()
BWClientConfiguration	withAsync(boolean value) Runs the bot in asynchronous mode.
BWClientConfiguration	withAsyncFrameBufferCapacity(int size) The maximum number of frames to buffer while waiting on a bot.
BWClientConfiguration	withAsyncUnsafe(boolean value) Enables thread-unsafe async mode.
BWClientConfiguration	withAutoContinue(boolean value) When true, restarts the client loop when a game ends, allowing the client to play multiple games without restarting.
BWClientConfiguration	withDebugConnection(boolean value) Set to `true` for more explicit error messages (which might spam the terminal).
BWClientConfiguration	withLogVerbosely(boolean value) Toggles verbose logging, particularly of synchronization steps.
BWClientConfiguration	withMaxFrameDurationMs(int value) The maximum amount of time the bot is supposed to spend on a single frame.
BWClientConfiguration	withUnlimitedFrameZero(boolean value) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BWClientConfiguration

public BWClientConfiguration()

Method Detail

withDebugConnection

public BWClientConfiguration withDebugConnection(boolean value)

Set to `true` for more explicit error messages (which might spam the terminal).

getDebugConnection

public boolean getDebugConnection()

withAutoContinue

public BWClientConfiguration withAutoContinue(boolean value)

When true, restarts the client loop when a game ends, allowing the client to play multiple games without restarting.

getAutoContinue

public boolean getAutoContinue()

withUnlimitedFrameZero

public BWClientConfiguration withUnlimitedFrameZero(boolean value)

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.

getUnlimitedFrameZero

public boolean getUnlimitedFrameZero()

withMaxFrameDurationMs

public BWClientConfiguration withMaxFrameDurationMs(int value)

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.

getMaxFrameDurationMs

public int getMaxFrameDurationMs()

withAsync

public BWClientConfiguration withAsync(boolean value)

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.

getAsync

public boolean getAsync()

withAsyncFrameBufferCapacity

public BWClientConfiguration withAsyncFrameBufferCapacity(int size)

The maximum number of frames to buffer while waiting on a bot. Each frame buffered adds about 33 megabytes to JBWAPI's memory footprint.

getAsyncFrameBufferCapacity

public int getAsyncFrameBufferCapacity()

withAsyncUnsafe

public BWClientConfiguration withAsyncUnsafe(boolean value)

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.

getAsyncUnsafe

public boolean getAsyncUnsafe()

withLogVerbosely

public BWClientConfiguration withLogVerbosely(boolean value)

Toggles verbose logging, particularly of synchronization steps.

getLogVerbosely

public boolean getLogVerbosely()