BWAPI  4.2.0
An API for interacting with Starcraft: Broodwar (1.16.1)
Public Member Functions | List of all members
BWAPI::AIModule Class Reference

Public Member Functions

 AIModule ()
virtual void onEnd (bool isWinner)
virtual void onFrame ()
virtual void onNukeDetect (Position target)
virtual void onPlayerLeft (Player player)
virtual void onReceiveText (Player player, std::string text)
virtual void onSaveGame (std::string gameName)
virtual void onSendText (std::string text)
virtual void onStart ()
virtual void onUnitComplete (Unit unit)
virtual void onUnitCreate (Unit unit)
virtual void onUnitDestroy (Unit unit)
virtual void onUnitDiscover (Unit unit)
virtual void onUnitEvade (Unit unit)
virtual void onUnitHide (Unit unit)
virtual void onUnitMorph (Unit unit)
virtual void onUnitRenegade (Unit unit)
virtual void onUnitShow (Unit unit)

Detailed Description

AIModule is a virtual class that is intended to be implemented or inherited by a custom AI class.

The Broodwar interface is guaranteed to be initialized if any of these predefined interface functions are invoked by BWAPI.

Warning
Using BWAPI in any thread other than the thread that invokes these functions can produce unexpected behaviour and possibly crash your bot. Multi-threaded AIs are possible so long as all BWAPI interaction is limited to the calling thread.
Note
Replays are considered games and call all of the same callbacks as a standard game would.

Constructor & Destructor Documentation

BWAPI::AIModule::AIModule ()

Member Function Documentation

virtual void BWAPI::AIModule::onStart () virtual

Called only once at the beginning of a game.

It is intended that the AI module do any data initialization in this function.

Warning
Using the Broodwar interface before this function is called can produce undefined behaviour and crash your bot. (During static initialization of a class for example)
virtual void BWAPI::AIModule::onEnd (bool isWinner) virtual

Called once at the end of a game.

Parameters
isWinnerA boolean value to determine if the current player has won the match. This value will be true if the current player has won, and false if either the player has lost or the game is actually a replay.
virtual void BWAPI::AIModule::onFrame () virtual

Called once for every execution of a logical frame in Broodwar.

Users will generally put most of their code in this function.

virtual void BWAPI::AIModule::onSendText (std::string text) virtual

Called when the user attempts to send a text message.

This function can be used to make the bot execute text commands entered by the user for debugging purposes.

Parameters
textA string containing the exact text message that was sent by the user.
Note
If Flag::UserInput is disabled, then this function is not called.
virtual void BWAPI::AIModule::onReceiveText (Player player, std::string text ) virtual

Called when the client receives a message from another Player.

This function can be used to retrieve information from allies in team games, or just to respond to other players.

Parameters
playerThe Player interface object representing the owner of the text message.
textThe text message that the player sent.
Note
Messages sent by the current player will never invoke this function.
virtual void BWAPI::AIModule::onPlayerLeft (Player player) virtual

Called when a Player leaves the game.

All of their units are automatically given to the neutral player with their colour and alliance parameters preserved.

Parameters
playerThe Player interface object representing the player that left the game.
virtual void BWAPI::AIModule::onNukeDetect (Position target) virtual

Called when a Nuke has been launched somewhere on the map.

Parameters
targetA Position object containing the target location of the Nuke. If the target location is not visible and Flag::CompleteMapInformation is disabled, then target will be Positions::Unknown.
virtual void BWAPI::AIModule::onUnitDiscover (Unit unit) virtual

Called when a Unit becomes accessible.

Parameters
unitThe Unit interface object representing the unit that has just become accessible.
Note
This function INCLUDES the state of Flag::CompleteMapInformation.
See also
onUnitShow
virtual void BWAPI::AIModule::onUnitEvade (Unit unit) virtual

Called when a Unit becomes inaccessible.

Parameters
unitThe Unit interface object representing the unit that has just become inaccessible.
Note
This function INCLUDES the state of Flag::CompleteMapInformation.
See also
onUnitHide
virtual void BWAPI::AIModule::onUnitShow (Unit unit) virtual

Called when a previously invisible unit becomes visible.

Parameters
unitThe Unit interface object representing the unit that has just become visible.
Note
This function EXCLUDES the state of Flag::CompleteMapInformation.
See also
onUnitDiscover
virtual void BWAPI::AIModule::onUnitHide (Unit unit) virtual

Called just as a visible unit is becoming invisible.

Parameters
unitThe Unit interface object representing the unit that is about to go out of scope.
Note
This function EXCLUDES the state of Flag::CompleteMapInformation.
See also
onUnitEvade
virtual void BWAPI::AIModule::onUnitCreate (Unit unit) virtual

Called when any unit is created.

Parameters
unitThe Unit interface object representing the unit that has just been created.
Note
Due to the internal workings of Broodwar, this function excludes Zerg morphing and the construction of structures over a Vespene Geyser .
See also
onUnitMorph
virtual void BWAPI::AIModule::onUnitDestroy (Unit unit) virtual

Called when a unit is removed from the game either through death or other means.

Parameters
unitUnit object representing the unit that has just been destroyed or otherwise completely removed from the game.
Note
When a Drone morphs into an Extractor, the Drone is removed from the game and the Vespene Geyser morphs into an Extractor.
If a unit is visible and destroyed, then onUnitHide is called just before this.
virtual void BWAPI::AIModule::onUnitMorph (Unit unit) virtual

Called when a unit changes its UnitType.

For example, when a Drone transforms into a Hatchery, a Siege Tank uses Siege Mode, or a Vespene Geyser receives a Refinery.

Parameters
unitUnit object representing the unit that had its UnitType change.
Note
This is NOT called if the unit type changes to or from UnitTypes::Unknown.
virtual void BWAPI::AIModule::onUnitRenegade (Unit unit) virtual

Called when a unit changes ownership.

This occurs when the Protoss ability Mind Control is used, or if a unit changes ownership in Use Map Settings .

Parameters
unitUnit interface object pertaining to the unit that has just changed ownership.
virtual void BWAPI::AIModule::onSaveGame (std::string gameName) virtual

Called when the state of the Broodwar game is saved to file.

Parameters
gameNameA String object containing the file name that the game was saved as.
virtual void BWAPI::AIModule::onUnitComplete (Unit unit) virtual

Called when the state of a unit changes from incomplete to complete.

Parameters
unitThe Unit object representing the Unit that has just finished training or constructing.