This guide will help you get JNIBWAPI up and running on your computer. Here is a short demo video of what the example 5-pool bot included in JNIBWAPI should do. To get a better idea of what you can do with JNIBWAPI, there is lots of information over at the BWAPI project page and the old BWAPI project page - note that the documentation relevant to JNIBWAPI 1.0 is for BWAPI 3.

Make sure you have the following components:

• Starcraft & Brood War and 1.16.1 update
• Windows (Mac/Linux are unsupported)
• Java JDK 1.7+ (32-bit recommended)
• BWAPI 3.7.4
• Chaoslauncher (included with BWAPI)
• JNIBWAPI 0.4+
• Eclipse IDE (any Java compiler/IDE will work but project files for Eclipse are provided to make setup easier)

1. Install Starcraft and Brood War expansion
2. Update to latest version (1.16.1)
3. Extract BWAPI files from zip
4. Follow the "Build Instructions" in the README in the BWAPI files
   • Note: make sure to run vcredist_x86.exe (included in the BWAPI files)
   • Note: the BWAPI instructions are aimed at those intending to compile bots in C++. You can skip any steps to do with compiling the BWAPI project.
5. Edit <Starcraft dir>/bwapi-data/bwapi.ini:
   • Change line 8 "ai = bwapi-data\AI\ExampleAIModule.dll, bwapi-data\AI\TestAIModule.dll" to "ai = NULL".
   • Remove line 9.
6. Extract JNIBWAPI files
7. In the release directory of JNIBWAPI, right-click run.bat and select Run as Administrator
   • Expected output: "Loaded client bridge library." "Bridge: BWAPI Client launched!" "Bridge: Connecting..."
   • If output is not as expected, see Troubleshooting below
8. Start Chaoslauncher as an Administrator and activate the BWAPI Injector Release and W-Mode plugins
9. Start the Starcraft game
   • Expected output: "Connected" "Bridge: waiting to enter match..."
10. Begin a custom game as Zerg (the race the example AI is designed to play)
11. The JNIBWAPI player should take control of the player's units and begin ordering units
    • Note: the game will freeze for a minute or two the first time a new map is played as BWTA has to analyze the map

Assuming that you have followed the previous guide, you should have an extracted copy of JNIBWAPI and be able to run the example AI. Now let's modify it!

1. In your JNIBWAPI directory, copy client-bridge-x86.dll and client-bridge-amd64.dll from release/ into the top level directory
   • Advanced: alternatively you can change the Working Directory of any run configurations you create (eg. in step 3), to the release/ directory. This is preferable if you are changing the C++ code as it will output DLLs to the release directory.
2. Run Eclipse as an Administrator, create a New Java Project, uncheck "Use default location" and set the location to be your JNIBWAPI folder. It should be able to determine the rest for itself. Click Finish.
3. Expand the project and look in the package jnibwapi. Right click ExampleAIClient.java, select Run As, then select Java application.
4. Ensure that the behaviour is as in the previous guide (you have just completed the equivalent of Step 7)
5. You are now ready to duplicate ExampleAIClient.java to your own class and begin development. Take a look at the documentation to find the available commands.

Note that when using the provided .dll, certain files need to remain in the expected location. In particular BWAPIEventListener.java and JNIBWAPI.java should be left in the jnibwapi package. The core of your AI (equivalent to ExampleAIClient.java) can be anywhere, and is recommended to be outside the jnibwapi package.

If you receive the error "Native code library failed to load" when running your bot, it is likely a problem of using 32-bit or 64-bit Java. Try installing 32-bit Java and telling Eclipse or the batch file to use it. To use a 32-bit JRE in Eclipse, go to: Run > Run Configurations > "JRE" tab > Installed JREs. To change it in the batch file, specify the full path to the 32-bit Java, usually: C:\Program Files (x86)\Java\jre7\bin\java.exe

If the game freezes for one or two minutes at the beginning of the match, it is because you're running a new map for the first time. BWTA is used to analyze the map, which takes some time. This should only happen once on every map.

Displayed inside StarCraft at the start of a match. This means that your bot was unable to connect to the game. First check if it is really running. Then try starting the game again a few times (this sometimes happens for no apparent reason).