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

isWinner

A 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

text	A 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

player	The Player interface object representing the owner of the text message.
text	The 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

player

The 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

target

A 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

unit	The 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

unit	The 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

unit	The 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

unit	The 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

unit	The 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

unit	Unit 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

unit	Unit 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

unit	Unit 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

gameName

A 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

unit	The Unit object representing the Unit that has just finished training or constructing.