Class header file: BWAPI/AIModule.h

AIModule is a class that is intended to be implemented or inherited by a custom AI class. The following callbacks available to AIs:

• onStart
• onEnd
• onFrame
• onSendText
• onReceiveText
• onPlayerLeft
• onNukeDetect
• onUnitDiscover
• onUnitEvade
• onUnitShow
• onUnitHide
• onUnitCreate
• onUnitDestroy
• onUnitMorph
• onUnitRenegade
• onSaveGame

Notes:

Using BWAPI in a different thread than the default one will produce unexpected results and possibly crash the program. Multi-threaded AIs are possible so long as all BWAPI interaction is limited to the default thread (during one of the call-backs).

onStart

void onStart();

BWAPI calls this at the start of a match. Typically an AI will execute set up code in this method (initialize data structures, load build orders, etc).

onEnd

void onEnd(bool isWinner);

BWAPI calls this at the end of the match. isWinner will be true if the AIModule won the game. If the game is a replay, isWinner will always be false.

onFrame

void onFrame();

BWAPI calls this on every logical frame in the game.

onSendText

void onSendText(std::string text);

If Flag::UserInput is enabled, BWAPI will call this each time a user enters a message into the chat. If you want the message to actually show up in chat, you can use Game::sendText to send the message to other players (if the game is multiplayer), or use Game::printf if you want the message to just show up locally.

onReceiveText

bool onReceiveText(Player* player, std::string text);

BWAPI calls this each time it receives a message from another player in the chat.

onPlayerLeft

bool onPlayerLeft(Player* player);

BWAPI calls this when a player leaves the game.

onNukeDetect

bool onNukeDetect(Position target);

BWAPI calls this when a nuclear launch has been detected. If the target position is visible, or if Complete Map Information is enabled, the target position will also be provided. If Complete Map Information is disabled and the target position is not visible, target will be set to Positions::Unknown.

onUnitDiscover

void onUnitDiscover(Unit* unit);

BWAPI calls this when a unit becomes accessible. If Complete Map Information is enabled, this will be called at the same time as AIModule::onUnitCreate, otherwise it will be called at the same time as AIModule::onUnitShow.

onUnitEvade

void onUnitEvade(Unit* unit);

BWAPI calls this right before a unit becomes inaccessible. If Complete Map Information is enabled, this will be called at the same time as AIModule::onUnitDestroy, otherwise it will be called at the same time as AIModule::onUnitHide.

onUnitShow

void onUnitShow(Unit* unit);

BWAPI calls this when a unit becomes visible. If Complete Map Information is disabled, this also means that the unit has just become accessible.

onUnitHide

void onUnitHide(Unit* unit);

BWAPI calls this right before a unit becomes invisible. If Complete Map Information is disabled, this also means that the unit is about to become inaccessible.

onUnitCreate

void onUnitCreate(Unit* unit);

BWAPI calls this when an accessible unit is created. Note that this is NOT called when a unit changes type (such as larva into egg or egg into drone). Building a refinery/assimilator/extractor will not produce an onUnitCreate call since the vespene geyser changes to the unit type of the refinery/assimilator/extractor. If the unit is not accessible at the time of creation (i.e. if the unit is invisible and Complete Map Information is disabled), then this callback will NOT be called. If the unit is visible at the time of creation, AIModule::onUnitShow will also be called.

onUnitDestroy

void onUnitDestroy(Unit* unit);

BWAPI calls this when a unit dies or otherwise removed from the game (i.e. a mined out mineral patch). When a Zerg drone becomes an extractor, the Vespene geyser changes to the Zerg Extractor type and the drone is destroyed. If the unit is not accessible at the time of destruction, (i.e. if the unit is invisible and Complete Map Information is disabled), then this callback will NOT be called. If the unit was visible at the time of destruction, AIModule::onUnitHide will also be called.

onUnitMorph

void onUnitMorph(Unit* unit);

BWAPI calls this when an accessible unit changes type, such as from a Zerg Drone to a Zerg Hatchery, or from a Terran Siege Tank Tank Mode to Terran Siege Tank Siege Mode. This is not called when the type changes to or from UnitTypes::Unknown (which happens when a unit is transitioning to or from inaccessibility).

onUnitRenegade

void onUnitRenegade(Unit* unit);

BWAPI calls this when an accessible unit changes ownership.

onSaveGame

void onSaveGame(std::string gameName);

BWAPI calls this when the user saves the match. The gameName will be the name that the player entered in the save game screen.