StarCraft ProxyBot


The StarCraft ProxyBot provides a java interface for developing a StarCraft AI. The bot uses socket communication to get the game state from the BroodWar API and issue commands.


Click images to enlarge.

ProxyBot Installation

  1. Follow the instructions for Broodwar API: here
  2. Now the Broodwar API module should be up and running
  3. Extract the files from
  4. You can compile the DLL for yourself, by overriding the ExampleAImodule.cpp and ExampleAIModule.h files OR use the included DLL in AIModule
  5. Replace the compiled DLL file with the DLL in starcraft/bwapi-data/ai
  6. Compile the java files in starcraftbot

Running the Bot

  1. Run the class: ProxyBot
  2. This should display the message: "Waiting for client"
  3. Start the chaos launcher
  4. Ensure that the BWAPI Injector is enabled
  5. Start StarCraft
  6. Create a single player game
  7. The workers should automatically start mining
  8. A GUI will pop up (if you have a second monitor extending your desktop)

Extending the Bot

The ProxyBot class provides the main hooks into StarCraft. All commands that can be called are contained at the bottom of the class. All orders require a unit id, which specifies the unit to send the order too. The ProxyBot also is responisble for maintaining the game state and is a singleton instance. The following functions are useful for getting the game state:

  • ProxyBot.getProxy().getUnits()
  • ProxyBot.getProxy().getMap()
  • ProxyBot.getProxy().getUnitTypes()
  • ProxyBot.getProxy().getStartingLocations()
  • ProxyBot.getProxy().getTechTypes()
  • ProxyBot.getProxy().getUpgradeTypes()
  • ProxyBot.getProxy().getPlayerID()
  • ProxyBot.getProxy().getEnemyID()
  • ProxyBot.getProxy().getPlayer()
  • ProxyBot.getProxy().getEnemy()

Some example code is provided in the class: StarCraftAgent

Message Protocol

onStart messages

1. AIModule sends to the ProxyBot an ACK
NewGame; PlayerIDforTheBot
:Player1ID; Player1Race; Player1Name; Player1PlayerType; Player1isAlly
:Player2ID; Player2Race; Player2Name; Player2PlayerType; Player2isAlly

2. AIModule waits for a response from the ProxyBot
-char array[4] specifying bot options, '1' for true, (e.g. 1100)

3. AIModule sends the starting locations to the ProxyBot
Locations:Location1x; Location1y:Location2x; Location2y:..

4. AIModule sends the starting locations to the ProxyBot
MapName:mapWidth:mapHeight:tile1Height; tile1Buildable; tile1Walkable:tile2Height; tile2Buildable; tile2Walkable:...
-counting tiles from left to right and top to bottom

5. AIModule sends the starting locations to the ProxyBot
Chokes:Choke1x; Choke1y:Choke2x; Choke2y:..

6. AIModule sends the base locations to the ProxyBot
Bases:Location1x; Location1y:Location2x; Location2y:..

onFrame messages

1. AIModule sends the unit status's to the ProxyBot
s; botMineralsCount; botGasCount; botSupplyUsed; botSupplyTotal; botResearchStatus; botUpgradeStatus
:unit1ID; unit1PlayerID; unit1TypeID; unit1TileX; unit1TileY; unit1Health; unit1Shields; unit1Energy; unit1RemainingBuildTime; unit1RemainingTrainTime; unit1RemainingResearchTime; unit1RemainingUpgradeTime; unit1OrderTimer; unit1OrderID; unit1Resources; unit1AddOnID; unit1MineCount
:unit2ID; unit2PlayerID; unit2TypeID; unit2TileX; unit2TileY; unit2Health; unit2Shields; unit2Energy; unit2RemainingBuildTime; unit2RemainingTrainTime; unit2RemainingResearchTime; unit2RemainingUpgradeTime; unit2OrderTimer; unit2OrderID; unit2Resources; unit2AddOnID; unit2MineCount
-bot research status, char array[47], defines the status of TechTypes. 0 = not upgraded, 1 = in progress, 4 = researched
-bot upgrade status, char array[63], defines the status of UpgradeTypes. 0 = not upgraded, 1-3 = upgrade level, 4 = in progress

2. AIModule waits for a list of commands from the ProxyBot
:command1ID; command1UnitID; command1Arg1; command1Arg2; command1Arg3
:command2ID; command2UnitID; command2Arg1; command2Arg2; command2Arg3




Ben Weber


Michael Mateas

Downloads contains two directories:

  • AIModule contains the C++ code
  • starcraftbot contains the Java code

Research Lab

Expressive Intelligence Studio

Groups and Channels: 
Posted: Jan.01.2010
Category: EIS