VM Setup

The easiest way to get started with Korhal is to run a virtual machine using the ready-to-go VM image. This comes with everything you need to get started immediately: Brood War, Chaos Launcher, BWAPI, Leiningen, and Cygwin come installed for your convenience.

Installation Guide

1. Fork and clone Korhal.

2. Download the virtual machine image.

3. Install VirtualBox. Once it is installed, also install the Extension Pack from that page.

   1. Ubuntu users: You will want to actually follow the instructions on that page and not just try to install from apt-get, which has an old version. You need to add the VirtualBox PPA.

4. Open VirtualBox and go to File -> Import Appliance. Select the .ova file you downloaded. VirtualBox will import the image and set it up to live on your machine permanently.

5. Before running the VM, go to Settings and do the following:

   1. In Shared Folders, change the /repos folder you see there to point to your fork of Korhal. This allows the guest OS to use the Korhal repo on your host OS.

   2. In Networking, go to Port Forwarding and then share port 7777 between the host and guest. This will allow you to access Korhal's nREPL server for easier debugging.

6. Run the VM and follow this procedure to start the AI:

   1. Open up the Cygwin terminal found on the Desktop.

   2. Navigate to /cygdrive/f, which will be the shared folder we set up earlier.

   3. Run 'lein run' to start the AI. When you see "Bridge: Connecting..." proceed to the next step.

   4. On the Desktop, run Chaos Launcher, then hit Start to start Brood War in a window.

   5. Start a game with the first player as Terran race. The AI should start playing the game.

7. If everything works, go delete the giant .ova file you downloaded earlier. You don't need it anymore.

FAQ

• lein run tells me I have an EOF error even though my file looks fine

  • Sometimes, a bug with Leiningen in Windows will corrupt the current version of the .jar file. The easiest way to correct this is to restart the instance. If you'd rather not do that, try lein clean, rm -rf target, and then kill all running java processes from taskmgr.

• Performance is very bad on retina MacBooks once StarCraft starts

  • Change VirtualBox's display mode to Scaled. This will map the guest OS to true pixels, which will give you quite a small screen but should make the performance issue go away.