Introduction

The tournament module is a RELEASE-only module that is specifically designed to control and monitor the flow of a tournament game.

BWAPI's Tournament mode is enabled when a tournament module has been specified in the configuration and loaded by BWAPI successfully.

Features

• Can restrict AI modules from making some specific calls, either partially or completely.
• Can filter calls made or replace the data as the call is being made.
• Can enforce flags or command optimization on game start.
• Runs all the callbacks that an AI module can and has access to all features of the Broodwar API.
• Ability to retrieve the time an AI module spent in a callback by using Game::getLastEventTime.
• Reduces the amount of spam ("BWAPI r#### using...") by allowing only one BWAPI host to broadcast tournament information.

Configuration

Simply compile the tournament module as you would an AI module and in the configuration under [ai], add tournament= and have it specify the location of your tournament module. An example configuration is below.

[ai]
ai = bwapi-data\AI\Aiur.dll
ai_dbg = bwapi-data\AI\DevAIModule.dll

; Used only for tournaments
; Tournaments can only be run in RELEASE mode
tournament = bwapi-data\AI\MyTournamentModule.dll

Callbacks

In addition to the normal AI callbacks, the tournament module has its own unique callbacks not available to an AI module.

onAction

bool onAction(int actionType, void *parameter = NULL);

Using an enumeration for actionType, and the parameter for that action (casted to a pointer for the appropriate parameter if a parameter exists, or ignored if none exist for that enum member), you can allow AI commands by returning true, or have BWAPI ignore them by returning false.

The enumeration in BWAPI::Tournament:: is as follows:

    enum ActionID
    {
      EnableFlag,
      ChangeRace,
      StartGame,
      PauseGame,
      ResumeGame,
      LeaveGame,
      RestartGame,
      SetLocalSpeed,
      SetTextSize,
      SetLatCom,
      SetGUI,
      SetMap,
      SetFrameSkip,
      Printf,
      SendText,
      SetCommandOptimizationLevel
    };

The ExampleTournamentModule has already layed out a switch statement with all of the enumerations, but this article will review a couple of them without the switch statement.

The following prevents an AI module from using enableFlag to enable CompleteMapInformation.

// The definition of the onAction callback
bool ExampleTournamentModule::onAction(int actionType, void *parameter)
{
  // check if actionType is EnableFlag, which corresponds to Game::enableFlag
  if ( actionType == BWAPI::Tournament::EnableFlag )
  {
    // Cast the parameter to a pointer to an integer and check if it is CompleteMapInformation
    if ( *(int*)parameter == BWAPI::Flag::CompleteMapInformation )
      return false; // Reject this action, the AI module cannot enable CompleteMapInformation
  }
  return true; // Allow everything else
}

Another example converts all printf statements to uppercase and remaps it to sendText to be broadcasted globally.

// The definition of the onAction callback
bool ExampleTournamentModule::onAction(int actionType, void *parameter)
{
  // check if actionType is Printf, which corresponds to Game::printf
  if ( actionType == BWAPI::Tournament::Printf )
  {
    // Convert all characters of parameter to uppercase
    for ( char *ptr = (char*)parameter; *ptr; ptr++ )
      *ptr = toupper(*ptr);

    // Make BWAPI send this text instead of just printing it
    Broodwar->sendText("%s", parameter);

    return false; // Don't allow BWAPI to continue with the printf command
  }
  return true; // Allow everything else
}

It is important to note that the tournament module does not restrict calls in itself. This includes calls in ALL the tournament module's callbacks.

onFirstAdvertisement

void onFirstAdvertisement();

When more than one BWAPI player is in a game, it will broadcast a tournament message with a delay based on the current player's ID. After this message has been broadcasted, the other players running BWAPI will not repeat it. The player that broadcasted the message first will call this function, and the other players will ignore it.

Again, an example is provided, but here is another.

void ExampleTournamentModule::onFirstAdvertisement()
{
  Broodwar->sendText("I'm the leader, so I will be the one doing the talking.");
  Broodwar->sendText("This tournament will not tolerate spam!");
}