How Korhal Works

Korhal connects to Brood War by implementing the BWAPIEventListener class provided by JNIBWAPI. This is all done in core.clj using gen-class. The result is a korhal.core Java object that receives callbacks from BWAPI. All of your code that writes to BWAPI needs to take place in these callbacks.

Korhal Engines and Thread Safety

Korhal spins up a series of independent threads, referred to as engines, to make decisions about what to do based on the state of the game. Each of these threads communicates with the others using Clojure reference types, and a few of them are in charge of issuing commands to your units in the game.

Additionally, when an engine wants to issue a command in the game, for example to issue a move command, the command must be wrapped in the wrap-api macro provided in the korhal.tools.queue namespace. This will defer the wrapped call to be executed during the next gameUpdate loop. Since BWAPI is entirely thread-unsafe, this is the only way to guarantee that your command will go through without corrupting shared memory referenced by BWAPI.