Using the Broodwar API

Using the Broodwar API

The AI Module class defines the Bot interface. Game state can be queried from the Game class and orders can be issued to the Unit class. See the following links for additional information:

Note that the AI module is invoked from the main loop in StarCraft. Therefore, the game pauses if the onFrame method does not return.

Bot cheat flags

The following flags can be set by the enableFlag method:

  • Flag::UserInput
    • Allows the user to issue orders to units
    • Defaults to false
    • Must be disabled for all tournaments
  • Flag::CompleteMapInformation
    • Provides the bot with complete map information
    • Does not remove “fog of war”
    • Defaults to false
    • Must be disabled for all tournaments, except for tournament 3

BroodWar Interface

The following methods are part of the AI Module interface:

  • onStart() - called once at the beginning of a game
  • onEnd() - called once at the end of a game
  • onFrame() - called every game cycle
  • onAddUnit(Unit* unit) - informs the bot that a new unit is in play
  • onRemoveUnit(Unit* unit) - informs the bot that a unit is no longer in play
  • onSendText(std::string text) - called when text is sent to the console


The Broodwar class defines the game state accessible to the bot. The following functions are useful:

  • virtual std::set< Player* > getPlayers() - gets the list of players
  • virtual std::set< Unit* > getAllUnits() - returns all of the units
  • virtual std::set< Unit* > getMinerals() - returns the mineral patches on the map
  • virtual std::set< Unit* > getGeysers() - returns the list of gas geysers
  • virtual void enableFlag(Flag::Enum flag) - enables a flag, such as perfect information
  • virtual int mapWidth() - width of the map, in tiles
  • virtual int mapHeight() - height of the map
  • virtual bool buildable(int x, int y) - specifies if the location is buildable
  • virtual bool walkable(int x, int y) - specifies if ground units can traverse the location
  • virtual int groundHeight(int x, int y) - the height at the location, 0-2
  • virtual std::set< TilePosition > getStartLocations() - the starting locations for bases


Bots issue commands by directly telling units the actions to perform. Here are some of the actions defined in the Unit class:

  • virtual bool attackMove(Position position) = 0;
  • virtual bool attackUnit(Unit* target) = 0;
  • virtual bool rightClick(Position position) = 0;
  • virtual bool rightClick(Unit* target) = 0;
  • virtual bool train(UnitType type) = 0;
  • virtual bool build(TilePosition position, UnitType type) = 0;