Jump to content
Sign in to follow this  


Recommended Posts

File Name: BWAPI Beta

File Submitter: XGhozt

File Submitted: 07 Jun 2010

File Updated: 07 Jun 2010

File Category: 1.16.1

Author: lowerlogic

Version: 2.7.2



| BWAPI Beta 2.7 |




The BWAPI web site http://code.google.com/p/bwapi/

Documentation http://code.google.c...iki/BWAPIManual

Google Group http://groups.google.com/group/bwapi

Bug Reports http://code.google.c...api/issues/list

IRC Channel QuakeNet #BWAPI


1. Introduction to BWAPI



The Brood War Application Programming Interface (BWAPI) is a free and open

source C++ framework for creating AI modules for Starcraft: Broodwar. Using

BWAPI, programmers can retrieve information on players and individual units

in Starcraft as well as issue a wide variety of commands to units, opening

the doors for custom AIs with new micro and macro algorithms.


This zip has all the necessary include files, libs, and dlls required to

compile and run an AI module and also comes with three projects to help get

you started in AI development with BWAPI:


- Example AI Module - This project shows how to build an AI module DLL which

is the standard way of making autonomous agents with

BWAPI. The Example AI Module shows how to print

"Hello world!" along with a bit of example code that

shows how to read information about the units in the



- Example AI Client - This project shows how to build an AI client program,

which is an experimental new way of making AIs for

BWAPI. Like the Example AI Module project, this

project shows how to print "Hello world!" along with a

bit of example code that shows how to read information

about the units in the game. Note that this approach

is extremely experimental and currently runs much

slower than using an Example AI Module.


- AI Module Loader - This project is a very simple AI client program which

can load and run Example AI Module DLLs, essentially

a way of making your AI Module run in a seperate

process without actually converting it to a client



Build Instructions:


1. Extract the entire zip to a folder on your computer.


2. Copy the contents of Chaoslauncher/ to your Chaos Launcher folder.


3. Copy the contents of Starcraft/ to your actual Starcraft folder.


4. Copy the contents of WINDOWS/ to your C:\WINDOWS or C:\WINNT folder (which

ever your version of Windows has).


5. Open ExampleProjects.sln in VC++ 2008 SP1 or VC++ 2008 Express Edition and

compile the project as RELEASE.

To do this:

5.1. Change the dropdown box in the top center of the window from "Debug" to


5.2. Click Build -> Build Solution. The Example AI Module is now compiled

into a dll.


All three projects are now built. To run the Example AI Module:


1. Copy Release/ExampleAIModule.dll to

<starcraft folder>/bwapi-data/AI/ExampleAIModule.dll


2. Open <starcraft folder>/bwapi-data/bwapi.ini and set ai_dll to

ExampleAIMdoule.dll if it isn't already.


3. Run Chaoslauncher with BWAPI Injector checked.


4. Start Starcraft: Broodwar and create a match, either single player or

multiplayer LAN (UDP). The melee and free-for-all game modes work best, and

BWAPI also works on some UMS maps.



To run the Example AI Client:


1. Open <starcraft folder>/bwapi-data/bwapi.ini and set ai_dll to NULL (or some

other file name that doesn't exist).


2. Run Release/ExampleAIClient.exe


3. Run Chaoslauncher with BWAPI Injector checked.


4. Start Starcraft: Broodwar and create a match, either single player or

multiplayer LAN (UDP). The melee and free-for-all game modes work best, and

BWAPI also works on some UMS maps.


2. The BroodWar Terrain Analyzer



This release of BWAPI also comes with BWTA 1.7, the Brood War Terrain

Analyzer, which analyzes the map and locates the choke points and possible

expansion locations. BWTA is still a work-in-progress and does not work on

every map, so it may crash the game. To run BWTA and analyze a map, type

"/analyze" in the game chat while playing a match with either the Example AI

Module loaded or the Example AI Client running. This will freeze the game for

a couple minutes while BWTA analyzes the map. Once BWTA is done analyzing the

map, the game will unfreeze and superimpose the outlines of regions,

chokepoints, and base locations on the screen using BWAPI's draw commands.

For more information, visit: http://code.google.com/p/bwta/


3. Basic AI Module



The Example AI Module mainly just shows how to set everything up to make an

AI module for BWAPI. Once you understand how the Example AI Module works, you

may be interested the Basic AI Module from the BWSAL project, which aims to

develop several robust components which execute basic tasks, such as

constructing buildings, training units, gathering resources, and build-order

management. For more information, visit: http://code.google.com/p/bwsal/


4. Bug Reports



BWAPI is currently in beta, so as you write custom AI modules using BWAPI

you may run into bugs or other problems. We cannot find all the bugs on our own

so as a beta tester your feedback is invaluable and can be very helpful for

improving BWAPI. When you find a bug, please describe what the bug is and, if

possible, how to reproduce the bug and post the report in either a new issue at



or in a message to the bwapi google group at



Additionally, the contents of the BWAPI global log may prove useful in tracking

down the bug, so when appropriate please include relevant contents of the file

<starcraft folder>/bwapi-data/logs/global.log


in your bug report. Thank you for beta testing BWAPI.




Changes from BWAPI Beta 2.7.1 to BWAPI Beta 2.7.2



Fixed a bug in GameImpl::spriteToUnit which caused the game to crash every once in a while.



Changes from BWAPI Beta 2.6.1 to BWAPI Beta 2.7.1



AIs can now connect from another process using BWAPIClient.lib.


New enums:


* Added enum EventType


New classes:


* Added class Event

* Added class UnitCommand

* Added class UnitCommandType


The following functions have been added:


* Added AIModule::onSaveGame - called when the user saves the single player match. Currently is triggered twice.

* Added Game::getEvents - returns the set of events for the frame

* Added Game::indexToUnit - returns the Unit currently at the given index in Starcraft's internal Unit table. Only available when the Complete Map Information flag is enabled.

* Added Game::isInGame - returns true if Broodwar is currently in a match

* Added Unit::isAttacking - returns true if the unit is attacking. Does not yet work for siege tanks or goliaths.

* Added Unit::isVisible(Player* player) - returns true if the given player can see the given unit. Only available in replays or if the complete map information flag has been enabled.

* Added Unit::issueCommand - general purpose function to issue any valid unit command.


All member functions of Race, TechType, UnitType, UpgradeType, WeaponType now return other objects by value instead of by pointer. For example TechType::whatResearches returns a UnitType object rather than a const pointer to a UnitType object.


The following Orders have been renamed:


* Nothing1 -> UnusedNothing

* Powerup1 -> UnusedPowerup

* Nothing2 -> Nothing

* RallyPoint1 -> RallyPointUnit

* RallyPoint2 -> RallyPointTile

* Morph1 -> ZergUnitMorph

* Morph2 -> ZergBuildingMorph

* BuildSelf1 -> TerranBuildSelf

* Build5 -> BuildNydusExit

* Enternyduscanal -> EnterNydusCanal

* BuildSelf2 -> ProtossBuildSelf

* CarrierIgnore1 -> ReaverCarrierMove

* HoldPosition1 -> CarrierHoldPosition

* ReaverHold -> ReaverHoldPosition

* RechargeShields1 -> RechargeShieldsUnit

* Rechargeshields2 -> RechargeShieldsBattery

* BuildingLiftoff -> BuildingLiftOff

* DroneLiftoff -> DroneLiftOff

* Liftoff -> LiftingOff

* Harvest5 -> Interrupted

* Pickup1 -> PickupIdle

* Pickup2 -> PickupTransport

* Pickup3 -> PickupBunker

* Powerup2 -> PowerupIdle

* HoldPosition2 -> HoldPosition

* HoldPosition3 -> QueenHoldPosition

* HoldPosition4 -> SuicideHoldPosition


Bug Fixes:


* Fixed a bug where Unit::getGroundWeaponCooldown would always return 0 for Siege Tanks and Goliaths.

* Fixed a bug where Unit::getAirWeaponCooldown would always return 0 for Goliaths.

* Fixed a bug with Unit::isConstructing - now also returns true when the unit's order is TerranBuildSelf, ProtossBuildSelf, ZergBuildSelf, BuildNydusExit, and BuildAddon.

* Fixed a bug with Unit::isIdle - now also returns true when the unit's order is Reaver, Neutral, TowerGuard, and Burrowed.

* Fixed a bug with Unit::isMorphing - now also returns true when the unit's order is ZergBirth.

* Fixed a bug where Unit::isTraining - would return true for morphing hatcheries, lairs, and hives.

* Fixed a bug where Unit::useTech would not work for Archon_Warp or Dark_Archon_Meld.

* Fixed a bug where Game::canBuildHere would return true for refineries over geysers that already have refineries on them.

* Fixed a bug where Game::setScreenPosition would crash the game if given a position with negative coordinate values.

* Fixed a bug where Game::isBuildable would return true for the inaccessible row of tiles at the bottom of the map.

* Fixed a bug where Game::isWalkable would return true for the four inaccessible rows of tiles at the bottom of the map.

* Fixed a bug where UnitType::maxGroundHits would return 0 for Terran Siege Tank Siege Mode, Terran Siege Tank Tank Mode, and Terran Goliath.

* Fixed a bug where UnitType::maxAirHits would return 0 for Terran Goliath.



Changes from BWAPI Beta 2.6 to BWAPI Beta 2.6.1



* Added Unit::getID - returns a unique ID for the unit.

* Fixed a crash inadvertently introduced in BWAPI Beta 2.6 related to the new mouse and key state functionality.



Changes from BWAPI Beta 2.5 to BWAPI Beta 2.6



* Added Unit::getLarva - returns a set of 0, 1, 2, or 3 larva units that have spawned from the given Hatchery, Lair, or Hive.

* Added Unit::getHatchery - returns the Hatchery, Lair, or Hive that spawned the given larva. Returns NULL if the unit is not a Zerg Larva.

* Added Unit::returnCargo - returns the worker's cargo (minerals/gas) to a nearby resource depot. Works the same way as the "Return Cargo" button in the Starcraft GUI.

* Added Position::getApproxDistance - an approximate distance function similar to the one starcraft uses.

* Added Player::isDefeated - returns true if the player has been defeated

* Added Player::isVictorious - returns true if the player has achieved victory.

* Added Game::getMousePosition - returns the position of the mouse on the screen.

* Added Game::getScreenPosition - returns the position of the screen on the map.

* Added Game::setScreenPosition - moves the screen to the given position on the map.

* Added Game::pingMinimap - pings the given position on the minimap.

* Added Game::getMouseState - returns true if the specified MouseButton is pressed

* Added Game::getKeyState - returns true if the specified Key is pressed


The following functions have changed in functionality:


* AIModule::onEnd is now called before any user interaction at the end of games and replays.

* Game::getFrameCount no longer increases while the game is paused, however AIModule::onFrame is still called.

* Unit::getRemainingTrainTime now returns the number of frames until the next larva spawns at the given Hatchery, Lair, or Hive. Works as before on other unit types.

* Unit::getDistance(Unit* target) now computes the distance between units more similar to the way starcraft computes distance between units when determining if a unit is in attack range.

* Unit::getDefenseMatrixPoints now returns actual defense matrix hit points (not multiplied by 256).


Bug fixes:


* Fixed a bug where scourge that suicide into other units would not produce an AIModule::onUnitDestroy message.

* Fixed a bug where Game::canUpgrade would sometimes return true even though the player did not have enough resources.

* Fixed a bug where Unit::cancelTrain would not cancel Terran Nuclear Missiles when called on a Terran Nuclear Missile Silo.

* Fixed a bug where Unit::isTraining would return false when called on a Terran Nuclear Missile Silo training a Terran Nuclear Missile.

* Fixed a bug where Unit::getTrainingQueue would return and empty list when called on a Terran Nuclear Missile Silo training a Terran Nuclear Missile.



Changes from BWAPI Beta 2.4 to BWAPI Beta 2.5



* Added a logging option to bwapi.ini - by default it is set to off.

* Added TechType::getRace (the function was declared before but not actually implemented).

* Added Unit::getBuildType - returns the building type a worker is about to construct. If the unit is a morphing Zerg unit or an incomplete building, this returns the UnitType the unit is about to become upon completion.


* Fixed TechTypes::Restoration.whatResearches() so that it now returns UnitTypes::Terran_Academy?.

* Fixed a bug where Game::canBuildHere would return true even when a nexus/command center/hatchery was too close to invisible minerals/geysers. The function now uses static mineral and geyser data and assumes mineral fields exist unless it can see the build tile where the mineral is supposed to be, and cannot see the mineral unit.

* Fixed a bug where Unit::isIdle would return false after a worker failed to start construction of a building.

* Fixed a bug where using Siege Tanks would cause the game to crash.

* Fixed a bug where BWAPI would crash on game end if a player left during the game.

* Fixed a bug where Unit::isGatheringGas would sometimes return false for drones harvesting gas into a morphing Hatchery.

* Fixed a bug where chat messages in multiplayer games would either appear garbled or not show at all.



Changes from BWAPI Beta 2.3 to BWAPI Beta 2.4



* Added AttackType class, however this won't be of much use until the Attack class is implemented (which will let AI Modules "see" projectiles, bullets, psi storms, lurker attacks, etc).

* Added Game::isExplored - returns true for tiles that are visible or were visible at some point earlier in the match.

* Added Unit::isBeingGathered - returns true for mineral patches and the three types of refineries when a unit is gathering from it.


* Renamed Game::buildable to Game::isBuildable

* Renamed Game::walkable to Game::isWalkable

* Renamed Game::visible to Game::isVisible

* Renamed Game::groundHeight to Game::getGroundHeight

* Added TilePosition versions of Game::isBuildable, Game::isVisible, Game::hasCreep, and Game::hasPower.


The following functions have changed in functionality:


* UnitType::seekRange now returns the seek range in pixels.

* UnitType::sightRange now returns the sight range in pixels.

* UnitType::maxHitPoints now returns actual max hit points (not multiplied by 256).

* Unit::getHitPoints now returns actual current hit points (not multiplied by 256).

* Unit::getShields now returns actual current shields (not multiplied by 256).

* Unit::getEnergy now returns actual current energy (not multiplied by 256).

* UnitType::canAttack now returns false for overlords, dropships, and other types of units that cannot attack.

* Player::hasResearched now returns true for abilities that the player has researched by default, such as Scanner Sweep.

* Game::getFrameCount now counts from 0. So the first frame is frame 0.

* Game::sendText now processes most cheat codes in single player games. For example, typing Broodwar->sendText("black sheep wall") will reveal the entire map.


Bug fixes:


* Fixed a bug where Game::isVisible would crash the program when called during a replay.

* Fixed a bug where Unit::setRallyPosition and Unit::setRallyUnit would not execute properly.

* Fixed a bug where Unit::patrol would appear to change the position of the unit to the target position.

* Fixed a bug where Unit::isStartingAttack would always be false for certain types of units, even when they were attacking.

* Fixed a bug where scanner sweep (and possibly other tech types that don't need to be researched) would not work.

* Fixed a bug where AIModule::onFrame would be called twice on the first frame.

* Fixed a bug where Unit::train would not allow more than one unit to be added to the training queue.

* Fixed a bug where AIModule::onUnitDestroy would not be called for units loaded into dropships/shuttles/overlords when the transport unit was destroyed.

* Fixed UnitType::topSpeed, Unit::getVelocityX, and Unit::getVelocityY. Everything should now be in pixels per frame.



Changes from BWAPI Beta 2.2 to BWAPI Beta 2.3



* bwapi.ini file no longer accepts curly brace definitions.


The following functions have been added:


* AIModule::onUnitRenegade - called when a unit changes ownership.

* AIModule::onPlayerLeft - called when a player leaves the game.

* AIModule::onNukeDetect - called when a nuclear launch has been detected. If the target position is visible at the time of launch (or complete map information is enabled), the target position is provided.

* Game::restartGame - restarts the single player match.

* Unit::getUpgradeLevel - returns the upgrade level of the unit.

* Unit::getVelocityX - returns the x component of velocity in pixels per frame.

* Unit::getVelocityY - returns the y component of velocity in pixels per frame.

* Player::leftGame - returns true if the player has left the game.

* UnitType::upgrades - returns the set of upgrades that can affect this UnitType.

* UpgradeType::whatUses - returns the set of unit types that are affected by this UpgradeType.


The following functions have been renamed:


* Unit::getCurrentDirection has been renamed to Unit::getAngle


* Player::researching has been renamed to Player::isResearching

* Player::researched has been renamed to Player::hasResearched

* Player::upgrading has been renamed to Player::isUpgrading

* Player::upgradeLevel has been renamed to Player::getUpgradeLevel


* Game::drawMapBox has been renamed to Game::drawBoxMap

* Game::drawMouseBox has been renamed to Game::drawBoxMouse

* Game::drawScreenBox has been renamed to Game::drawBoxScreen


* Game::drawMapTriangle has been renamed to Game::drawTriangleMap

* Game::drawMouseTriangle has been renamed to Game::drawTriangleMouse

* Game::drawScreenTriangle has been renamed to Game::drawTriangleScreen


* Game::drawMapCircle has been renamed to Game::drawCircleMap

* Game::drawMouseCircle has been renamed to Game::drawCircleMouse

* Game::drawScreenCircle has been renamed to Game::drawCircleScreen


* Game::drawMapEllipse has been renamed to Game::drawEllipseMap

* Game::drawMouseEllipse has been renamed to Game::drawEllipseMouse

* Game::drawScreenEllipse has been renamed to Game::drawEllipseScreen


* Game::drawMapDot has been renamed to Game::drawDotMap

* Game::drawMouseDot has been renamed to Game::drawDotMouse

* Game::drawScreenDot has been renamed to Game::drawDotScreen


* Game::drawMapLine has been renamed to Game::drawLineMap

* Game::drawMouseLine has been renamed to Game::drawLineMouse

* Game::drawScreenLine has been renamed to Game::drawLineScreen


When complete map information is disabled, the following function no longer provide information about enemy units, regardless of visibility:


* Unit::isHallucination

* Unit::isLoaded

* Unit::getTrainingQueue

* Unit::getTransport

* Unit::getLoadedUnits

* Unit::getScarabCount

* Unit::getSpiderMineCount

* Unit::getTech

* Unit::getUpgrade

* Unit::getRemainingResearchTime

* Unit::getRemainingUpgradeTime

* Unit::isResearching

* Unit::isUpgrading

* Unit::getRallyPosition

* Unit::getRallyUnit


To determine if a visible enemy unit is busy researching or upgrading, use Unit::isIdle.


The following functions have changed in functionality:


* Unit::getAngle (renamed from Unit::getCurrentDirection) now returns the angle of the unit in radians.

* UnitType::topSpeed now returns the correct top speed of the UnitType in pixels per frame.

* Game::leaveGame now goes to the after-match stats screen, rather than going to the main menu.

* AIModule::onEnd is now called with an argument isWinner, which is true if the ai module has won the game.


Bug fixes:


* Fixed a bug where Game::drawTextMap would use screen coordinates. It now uses map coordinates as expected.

* Fixed a bug where attackUnit, rightClick, and other orders which take a target unit would not target the right unit in the game.

* Fixed a bug where Unit::isGatheringGas and Unit::isGatheringMinerals would sometimes return false, even though the unit was gathering gas/minerals.

* Fixed a bug where getUnits() functions would return an incomplete list of units when called from onUnitMorph, onUnitShow, or onUnitHide.


Other changes:


* Added documentation of how to draw text in different colors.

* Increased speed of multiplayer menus.



Changes from BWAPI Beta 2.1 to BWAPI Beta 2.2



The following functions have been added:


* AIModule::onUnitShow

* AIModule::onUnitHide

* AIModule::onUnitMorph


* Unit::getInitialType

* Unit::getInitialPosition

* Unit::getInitialTilePosition

* Unit::getInitialResources

* Unit::getInitialHitPoints


* Game::isMultiplayer

* Game::isPaused


* Game::getStaticMinerals

* Game::getStaticGeysers

* Game::getStaticNeutralUnits


* Game::drawTextMap

* Game::drawTextMouse

* Game::drawTextScreen


* Game::drawMapBox

* Game::drawMouseBox

* Game::drawScreenBox


* Game::drawMapTriangle

* Game::drawMouseTriangle

* Game::drawScreenTriangle


* Game::drawMapCircle

* Game::drawMouseCircle

* Game::drawScreenCircle


* Game::drawMapEllipse

* Game::drawMouseEllipse

* Game::drawScreenEllipse


* Game::drawMapDot

* Game::drawMouseDot

* Game::drawScreenDot


* Game::drawMapLine

* Game::drawMouseLine

* Game::drawScreenLine


The following functions have changed in functionality:


* Unit::exists - now returns false for inaccessible units, even if they exist.

* AIModule::onUnitCreate is no longer called for invisible units when complete map information is disabled.


The following functions have been renamed:


* Game::text has been renamed to Game::drawText

* Game::inReplay has been renamed to Game::isReplay

* AIModule::onAddUnit has been renamed to AIModule::onUnitCreate

* AIModule::onRemoveUnit has been renamed to AIModule::onUnitDestroy


Other changes:


* BWAPI no longer crashes on replays.



Changes from BWAPI Beta 2 to BWAPI Beta 2.1



* Fixed a bug that produced phantom marines. An internal unit set in BWAPI

was not being reset between matches, so units that existed in a previous

match appeared to exist in the next game as phantom marines. Retrieving

information from these non existant marines and/or issuing orders to them

may have also caused Broodwar to crash.



Changes from BWAPI Beta to BWAPI Beta 2



The following functions have been added:


* Unit::isCarryingGas

* Unit::isCarryingMinerals

* Unit::isDefenseMatrixed

* Unit::isEnsnared

* Unit::isIrradiated

* Unit::isMaelstrommed

* Unit::isParasited

* Unit::isPlagued

* Unit::isStimmed


* Game::leaveGame - replaces Game::surrender and now works correctly.

* Game::setLocalSpeed - lets AIs increase the speed in single player games.


Other changes:


* Fixed crash due to null sprite pointer in Broodwar memory

* Minor update of UnitType information for spells and Terran Nuclear Missile.

* Minor update of description text shown in Chaoslauncher text box.

* Example AI Module compiles much faster due to new compile of BWTA.lib.


Click here to download this file

Share this post

Link to post
Share on other sites

Hi, I'm a project owner of BWAPI and I would like to request the removal of the BWAPI Beta 2.7 download.


BWAPI Beta 2.7 is heavily outdated and can misguide users into using unsupported versions of BWAPI.

Instead, I think a link to the project page would be more appropriate.


BWAPI is still an active project and is currently at version 3.6.1 (1555 revisions after 2.7.2). See the change log for the differences between 2.7 and the current version.


Just a side note: The AIIDE2011 Starcraft competition begins on the 15th of this month (very soon), and the CIG2011 competition begins on the 31st. There will be more competitions to come as well.

Share this post

Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this